Message definitions

When you add a new message definition, you are associating a root element with a schema you have imported into the Message Bridge GUI. The root element is defined in the imported schema. Sometimes a message definition incorporates all the root elements from an imported schema. Other times, your message definition may use only one of many root elements of the imported schema, making it in effect, a subset of the schema.

Your message definition determines the API of the code Message Bridge generates. The generated code binds the schema to a Java DataBean that you can use in an application. See Chapter 2, “Understanding the DataBean Framework”, for more information on DataBeans.

This section covers the following topics:

• Adding a message definition for a DTD

• Adding a message definition for an XML Schema

Adding a message definition for a DTD

You can add a message definition by importing a Document Type Definition (DTD). When you add a message definition, Message Bridge binds the root element to the DTD. To add a message definition, you must know the root elements of the DTD you want to import.

To add a message definition for a DTD

1. In the Definitions panel, select a Schema Group. Select Default Group if no others exist. See Schema groups for information on new schema groups.

2. Go to File | New | Message Definition. The Add Message Schema dialog box opens.

3. In the Metadata Source drop-down list, use the default selection, DTD Importer. In the Files of Type drop-down list, use the default selection, Document Type Definition (DTD).

4. Enter the name of the DTD you want to import. You can change directories by clicking the Down arrow in the Look In drop-down list. Navigate to the directory where the DTD file resides and select the file.

5. Click OK. The Select Root Element dialog box opens.

   If your DTD has namespaces, see Defining namespaces in message definitions that use DTDs. Elements with colons signify namespaces.

6. Select a root element from the DTD that corresponds to the document for this message definition. Click OK.

   To find the root element of the DTD you are importing, review the DTD file you imported in a text editor.

   The DTD you imported appears in the Definitions panel, and a graphical representation of the DTD appears in the Message Bridge GUI. The representation shows the element you selected as root and its children, as defined in the DTD.

   You can now continue defining your message by:

   • Defining namespaces in message definitions that use DTDs

   • Modifying an element name

   • Creating views

Adding a message definition for an XML Schema

You can add a message definition by importing an XML Schema. When you add a message definition, Message Bridge binds the root element to the XML Schema. To add a message definition, you must know the root elements of the XML Schema you want to import.

To add a message definition for XML Schema

1. In the Definitions panel, select a Schema Group. Select Default Group if no others exist. See Schema groups for information on new schema groups.

2. Go to File | New | Message Definition. The Add Message Schema dialog box opens.

3. In the Metadata Source drop-down list, select XML Schema Importer. In the Files of Type drop-down list, XML Schema (.xsd) becomes the default.

4. Enter the name of the XML Schema you want to import. You can change directories by clicking the Down arrow in the Look In drop-down list. Navigate to the directory where the XML Schema resides and select it.

5. Click OK. The Select Root Element dialog box opens.

6. Select a root element from the XML Schema that corresponds to the document for this message definition. Click OK.

   To find the root element of the XML Schema you are importing, review the XML Schema file you imported in a text editor.

   The XML Schema you imported appears in the Definitions panel, and a graphical representation of the XML Schema appears in the Message Bridge GUI. The representation shows the element you selected as the root and its children, as defined in the XML Schema.

   You can now continue defining your message by:

   • Defining namespaces in message definitions that use DTDs

   • Modifying an element name

   • Creating views

Defining namespaces in message definitions that use DTDs

If you are using a DTD with namespaces, you must register the namespace Uniform Resource Identifier (URI) in the Message Bridge GUI. In order to generate Java bound to your message definition, the URIs must be registered. Since XML Schemas support a namespace declaration, their URIs are automatically registered in the GUI.

You have to determine which elements and attributes have namespaces. Look at the DTD or go to the Select Root Element dialog box. You also have to know the URI of each namespace. When you import your DTD, Message Bridge will assume that every colon represents a namespace.

To register namespaces in DTDs

1. Elements with namespaces appear in the Select Root Element dialog box with colons. The Select Root Element dialog box opens when you import your DTD. See Adding a message definition for a DTD to import a DTD. Note the elements that have colons; you are required to register their URIs.

2. Find an element or attribute with a namespace in the graphical representation of the DTD and select it.

3. In the Properties panel, below the Definitions panel, the namespace prefix appears in the Value field. Enter the URI in the Value field of Namespace URI, for example, sybase=http://sybase.com/sybase.

   The URI is registered for all instances of the namespace when you register it for one.

   Because namespaces are not supported in DTDs, you have to get the URI from the author of the DTD. If you have an XML document that conforms to the DTD, the URI is in the document.

4. Repeat steps 2 and 3 for all namespaces.

Modifying an element name

Because the application you are writing may have local naming conventions or styles to conform with, Message Bridge allows you to change the name of an element that occurs in the code it generates. You change the name in the graphical representation of your schema. The name of the element does not change in the schema, only in the GUI. Your modified name occurs in the DataBean.

To modify an element name

1. Select the element whose name you want to modify.

2. Right-click the element name in the graphical representation of the schema.

   If you right-click an attribute and select Rename Element, you rename the element above the attribute. Renaming attributes is not supported.

3. Select Rename Element. The Rename Object dialog box opens.

4. Enter the new name of the element and click OK. The new name appears in the graphical representation of the schema.

Creating views

You can create a view on one of your message definitions and create a subset of the schema. A graphical representation of the view is displayed in the GUI.

To create a view

1. Open the message definition from which you want to create a view.

2. Right-click an element that is part of the view you want to create. Message Bridge automatically includes all the parents and children of the element you select.

3. Select New View. The View Name dialog box opens.

4. Enter a name for your view. Click OK. A graphical representation of your view appears.

Copyright © 2005. Sybase Inc. All rights reserved.