Professional Documents
Culture Documents
Palette Reference
Software Release 5.6
July 2008
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN TIBCO Designer User’s Guide OR IF THERE IS NO SUCH
SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S)
LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO
THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF
AND AN AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright
laws and treaties. No part of this document may be reproduced in any form without the written
authorization of TIBCO Software Inc.
TIB, TIBCO, Information Bus, The Power of Now, TIBCO Adapter, TIBCO Administrator, TIBCO
ActiveMatrix BusinessWorks, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO
Rendezvous, TIBCO Repository, and TIBCO Runtime Agent are either registered trademarks or
trademarks of TIBCO Software Inc. in the United States and/or other countries.
EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of
Sun Microsystems, Inc. in the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL
OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME
TIME. SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A
SPECIFIC OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.
CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE
IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING
BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 1999-2008 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
| iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Figures
Tables
Preface
TIBCO Designer is an easy to use graphical user interface for creating and
deploying integration projects. TIBCO Designer allows you to drag and drop
components into a project and then specify configuration information for each
component.
Topics
Related Documentation
TIBCO Designer groups configuration resources into palettes. For each TIBCO
Designer palette, there is a separate book, available via online help. You can
access the different books in various ways:
• From TIBCO Designer, choose Help > Help For, then select the palette you are
interested in.
• From TIBCO Designer, right-click any resource to get documentation about it.
• The books are also available in HTML and PDF in the d o c folder for the
product in question.
As a rule, TIBCO Designer is not installed standalone but in conjunction with
another product. Most palettes are product specific, however, a number of
palettes are included with TIBCO Designer by default and included in this
document.
See the TIBCO Designer Release Notes for information about new features and
known and closed issues.
Typographical Conventions
Convention Use
code font Code font identifies commands, code examples, filenames, pathnames, and
output displayed in a command window. For example:
Use M y C o m m a n d to start the foo process.
Key Key name separated by a plus sign indicate keys pressed simultaneously. For
combinations example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply
the information provided in the current section to achieve a specific result.
Convention Use
The warning icon indicates the potential for a damaging situation, for example,
data loss or corruption if certain steps are taken or not taken.
Convention Use
[ ] An optional item in a command or code syntax.
For example:
MyCommand [optional_parameter] required_parameter
| A logical ’OR’ that separates multiple items of which only one may be chosen.
For example, you can select only one of the following parameters:
MyCommand para1 | param2 | param3
In the next example, the command requires two parameters. The first parameter
can be either p a r a m 1 or p a r a m 2 and the second can be either p a r a m 3 or p a r a m 4 :
MyCommand {param1 | param2} {param3 | param4}
In the next example, the command can accept either two or three parameters.
The first parameter must be p a r a m 1 . You can optionally include p a r a m 2 as the
second parameter. And the last parameter is either p a r a m 3 or p a r a m 4 .
MyCommand param1 [param2] {param3 | param4}
For comments or problems with this manual or the software it addresses, please
contact TIBCO Support as follows.
• For an overview of TIBCO Support, and information about getting started
with TIBCO Support, visit this site:
http://www.tibco.com/services/support
• If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user
name, you can request one.
Topics
• AliasLibrary, page 3
• Enterprise Archive, page 4
• Folder, page 5
• Generic Image Resource, page 6
• Identity, page 7
• LibraryBuilder, page 9
• Task List, page 10
• Text Document, page 12
Introduction
When you install TIBCO Designer as part of a TIBCO Runtime Agent installation,
a small number of default palettes are included. This document is a reference to
each of these default palettes. Some step-by-step instructions are included where
appropriate.
When you install other products that use TIBCO Designer, such as TIBCO
ActiveMatrix BusinessWorks or a custom adapter, those products add palettes
and corresponding palette documentation to TIBCO Designer.
AliasLibrary
The AliasLibrary resource allows you to specify aliases to file system resources
(such as a . j a r file) that need to be included in your project. To use a file system
resource, a project needs to know where to find it. Since projects are exported or
deployed to different machines and different environments, TIBCO Designer uses
aliases to specify file locations.
When including a file, an alias is created that specifies the file’s location. An alias
is part of your preferences and is common to all of your projects. Aliases are
created and managed under the File Alias tab in the Preferences dialog.
Resources that reference an AliasLibrary package all the referenced files when
their enterprise archive file is built. Because AliasLibraries reference files via a
reference, you must ensure that the machine where the enterprise archive file is
generated can access all externally referenced files.
See Creating an AliasLibrary on page 95 in TIBCO Designer User’s Guide for more
information.
Enterprise Archive
When you are ready to deploy your project, you must generate an enterprise
archive file. An enterprise archive file contains information about the adapter
instances and process engines you wish to deploy, and additional files that may
be required to support your configuration.
See Chapter 6, Creating an Archive for Deployment in TIBCO Designer User’s
Guide for details.
Folder
Folders are used to organize resources. TIBCO Designer palettes, such as the
Adapter Resource or Adapter Schema palette, use folders to organize resources.
TIBCO Designer users can also use folders to organize the resources in their
projects.
TIBCO Designer supports two kinds of folders:
Identity
Certificate URL Location of the certificate. Click the browse icon or type in
a URL. Note that you can add the certificate in PEM format
by choosing Tools > Trusted Certificates > Import into
PEM Format.
Key URL Location of the private key file associated with the
certificate.
Identity File
Use this option of the certificate includes the private key information in the same
file.
Username/ Password
Use this option if you want to use a username and password for authentication
and don’t want to use a certificate. Supply information in the following fields:
LibraryBuilder
Task List
TIBCO Designer allows you to create one or more task lists and include them with
your project. Each task list can describe either a project or a project component
and consists of a number of tasks. As the tasks are updated by their owners, the
task list itself is updated.
The advantage of task list resources is that they are always saved and opened as
part of the project.
To use a task list, follow these steps:
1. With the top-level folder selected, select the P r o j e c t Tracker palette if in
palette mode.
2. Drag a T a s k List resource from the palette panel into the design panel.
3. Supply information about the task list name and subject, a description, and
the owner of the list, then click Apply.
4. Select the task list. A new set of icons appears in the tool bar.
Icon Description
Add task list. Adds a task list to the currently selected task list. Task
lists can contain both tasks and task lists.
Add task. Adds a task to the currently selected task list. You can later
convert the task to a task list if desired.
Move up. Moves the selected task or task list up in the hierarchy.
Move down. Moves the selected task or task list down in the
hierarchy.
Convert to task list. Converts a selected task into a task list. This is
useful when you realize that a task you created actually consists of a
number of subtasks.
5. Drag tasks and task lists into the design panel as needed.
6. For each task or task list, you can specify the following information:
— Task Subject
— Description
— Owner
— Completed
7. Then click the Details tab to specify the following information:
You can only specify Detail information for tasks, not for task lists. When you
have completed all tasks in a task list, the task and task lists are checked in the
task hierarchy.
If you do not choose the format month/day/year for the dates, a "bad value"
error results.
8. The task list is now saved with the project. Each time a developer wishes to
make a change to one of the tasks, she may do so and the task list will be
updated appropriately.
Text Document
The T e x t D o c u m e n t resource can be used as a simple text file for notes that you
can associated with your project or place in folders inside the project.
For each T e x t Document, you can provide a name (which appears as the label)
and the text.
The XML Tools palette provides a set of tools enabling the creation, management,
and validation of XML schemas (XML Schema or DTD) and XML instance
documents.
Topics
Introduction to XML
XML provides a flexible set of structures that can hold different types of
information, from highly structured database tables and lists to more free-form
documents. The tightly defined requirements for XML documents ensure that all
applications adhere to the same rules when they read (technically, parse) and
write documents. The XML 1.0 specification leaves little room for conflicting
syntactical interpretations of the same XML document. As a result, it allows the
exchange of documents across a wide variety of platforms, applications, and
development environments.
The XML Tools palette allows you to create and define the following types of
XML resources:
• DTD — A Document Type Definition (DTD), the schema language specified
by the W3C XML 1.0 specification.
• Schema — An XML Schema, as defined by the W3C Recommendation (May
2001).
• Instance — An XML document conforming to either an XML Schema or DTD.
(The Instance resource can also be used to create XML documents that do not
use a schema.)
Schemas and DTDs can be used in several places within your integration project.
For example, WSDL files (files that describe web services) use schemas to define
the input and output messages of a web service. Several TIBCO ActiveMatrix
BusinessWorks activities have Input Editor or Output Editor tabs where you can
use a reference to a defined schema.
TIBCO provides partial support for XML Schema redefines in design-time editing
of XSD schemas and runtime processing of XML. There are some known issues
with complex, multi-level usage of this feature of the schema language that
manifest in the TIBCO ActiveMatrix BusinessWorks Mapper activity and in
runtime validation of data.
Given the industry trend away from this XSDL feature, TIBCO has no plans to
further enhance support. It is recommended that schema authors use other
features of the language to create similar patterns of inheritance and restriction,
such as type extension, substitution groups, and so on.
Please contact TIBCO Support if you need help with schema design alternatives.
2. From the palette panel, drag a Schema, DTD, or Instance icon into the design
panel to add that resource to your project.
Existing XML resources can be added to a folder in your project by way of the
Project menu (Project > Import Resources from File, Folder, URL...).
Features
When you select a Schema or DTD resource in the project panel, a set of new
panels becomes available. You can use these panels to create, validate, and
manage the schema resource. Features include:
• Real-time DTD error checking
• Graphical representations of schemas for intuitive development and
communication
Content Model
Diagram
Configuration
Panel
When you begin work on a new XML Schema or DTD, most of your work is
performed in the Element/Types Panel, which is used to declare the elements,
complex types, and attributes that define document structure and describe data
content.
1. Drag a S c h e m a resource from the palette panel to the design panel and
double-click it to open it.
2. If starting a new document, tab to the E l e m e n t column and replace r o o t with
Book.
Names must begin with a letter and may contain numbers, underscores,
dashes, and full stops -- typically periods.
3. Ignore the D e r i v e s F r o m column for now as this declaration will not be
derived from an existing complex type definition.
4. Tab to the C o n t e n t column and select the appropriate content type from the
C o n t e n t T y p e button. In this example, the content for B o o k will contain other
elements (such as C h a p t e r ), so select E l e m e n t s .
5. Tab to the C o n t e n t M o d e l column and type in the content model of the book.
A simple content model for B o o k might look like the one shown below. See
If the content model contains references to sub-elements that are not yet
declared, a prompt to create entries for these elements will appear.
6. Select C r e a t e new elements as Locally defined and click Create.
XML Schema elements can be declared locally or globally. Local elements exist
within the context of their parent element only. Accordingly, you could have a
local element named t i t l e that appears within a b o o k element and another local
element named t i t l e that appears within a m o r t g a g e element. Global elements
are declared such that they can be referenced within any content model. All global
elements must have unique names.
The Elements/Type panel always appears beneath the content model diagram.
The content model diagram only appears if the Elements/Type panel is selected.
The content model diagram provides a graphical overview of your schema.
This serves as a brief introduction into the types of declarations used to build
your schema. An overview of the other panels used to build your I n s t a n c e
resources is provided in Table 3 on page 24.
For step-by-step XML Schema building exercises, see XML Schema Exercises on
page 70. To build a sample DTD, see DTD Exercise on page 113.
Select the desired schema from your project and indicate the element to serve
as the root element for the document. Most of your work will be performed in
the content panel, which consists of a listing of the elements and attributes
(tag area) on the left and an area for inserting values for the elements and
attributes (edit area) on the right.
3. To enter data for an element or attribute (if allowed by the schema), click the
corresponding field in the edit area and type in the value.
When a new schema is set, content hints appear as grayed-out text strings in the
edit area. The content hints indicate the expected content, as defined by the
schema, for the associated element or attribute in the tag area. For more
information, see Content Hints on page 132.
4. When a new schema is set, only required elements and attributes appear in
the tag area. To add more elements or attributes, double click an element to
generate a drop down box.
This box always contains an empty box with a series of icons below. These
icons, when selected, determine the type (element, attribute, and so on) and
location (child, sibling, parent) of the node to be entered. If the document is
based on a schema, any elements and attributes available based on the
schema's content models also appear in the insert drop down box, and can be
added with a single mouse click.
insert new element
insert new attribute
insert schema-defined
element or attribute
The factory bar at the bottom of the content panel, provides another option for
entering new elements and attributes.
An overview of the other panels you can use to build your I n s t a n c e resources is
provided in Table 3 on page 24.
Panels
When working with a resource from the XML Tools palette, new panels are
provided to help you review and refine the resource. The panels are summarized
in the Table 3.
Validation or All The errors or validation panel displays warnings and errors
Errors detected throughout the editing process. For more information
on the errors or validations panel, see:
• Validations Panel, page 68 (Schema)
• Errors Panel, page 110(DTD)
• Errors Panel, page 135 (Instance)
Elements/Types Schema The elements/types panel enables you to view, create, and edit
and DTD element and attribute declarations and complex type definitions.
The elements/types panel is typically the place you'll start
defining your schemas. For more information on the
elements/types panel, see:
• Elements/Types Panel, page 40 (Schema)
• Elements Panel, page 84 (DTD)
Note: This panel is referred to as the elements panel when
working with DTD resources.
Content Instance The content panel provides the primary editing area. The panel
loads by default when an I n s t a n c e resource is selected in the
project panel. The content panel consists of a left-hand listing of
the elements and attributes (tag area) and a right-hand area for
inserting values for the elements and attributes (edit area). For
more information on the content panel, see Content Panel,
page 121.
Attributes Schema The attributes panel is used to view, create, and edit attribute
and DTD type declarations. For more information on the attributes panel,
see:
• Attributes Panel, page 50 (Schema)
• Attributes Panel, page 93 (DTD)
Advanced Schema The advanced panel is used to define or edit parts of XML
and DTD schemas that move beyond the description of document
structures, such as namespaces, notations, entities, and
processing instructions. For more information on the advanced
panel, see:
• Advanced Panel, page 63 (Schema)
• Advanced Panel, page 103 (DTD)
Simple Types Schema The simple types panel enables XML Schema authors to create
their own types (simple types), which can then be applied to
element declarations and attributes in the schema. For more
information on the data types panel, see:
• Simple Types Panel, page 66
Component Doc Schema The component doc or notes panel provides an area where you
or Notes and DTD can add schema or declaration level documentation.For more
information on the component doc or notes panel, see:
• Component Doc Panel, page 68 (Schema)
• Notes Panel, page 110 (DTD)
• Row Selector/ Error Indicator — This column contains grey or red dots
located at the start of each row on the left. Right-clicking on a dot brings up a
menu offering cut, copy, paste, and delete or clear options. (Multiple rows can
be selected at a time using the Shift and Ctrl keys). A red dot indicates there is
an error in the declaration. If you hover the mouse cursor over a red dot for a
few seconds, a description of the declaration's error is displayed.
• Included Document Indicator — This column indicates whether a declaration
comes from the file being edited. If a small document icon with a red line
through it appears in this space, the declaration cannot be edited directly here,
because the declaration comes from a file that has been included from the
overview panel. To edit these declarations, right click the document icon and
choose unlock. Be aware, however, that any changes made to the declarations
will be reflected in the original (external) document as well.
Toolbar Buttons
When editing or viewing XML Tools resources, additional buttons appear on the
toolbar. The toolbar buttons are described in Table 4.
Schema and DTD Opens the attributes panel. If the button is dimmed,
the panel is already open.
Menu Options
When editing resources in the XML Tools palette, menus become available for
performing various operations. For Schema and DTD resources, the Schema
menu becomes available. For Instance resources, the XML Menu becomes
available. The following sections describe the options available for these menus.
Schema > View Element/Types Opens the element/types panel. If the option is
dimmed, the panel is already open.
Note: This panel is referred to as the elements panel
when working with DTD resources.
Schema > View Simple Types Opens the simple types panel. If the option is
dimmed, the panel is already open.
Note: This option is available for Schema resources
only.
Schema > View Attributes Opens the attributes panel. If the option is dimmed,
the panel is already open.
Schema > View Advanced Opens the advanced panel. If the option is dimmed,
the panel is already open.
Schema > View Source Opens the source panel. If the option is dimmed, the
panel is already open.
Schema > View Notes or Component Opens or closes the notes or component doc panel.
Doc
Schema > View Errors or Validation Opens or closes the errors or validation panel.
Schema > View Zoom In Makes the items in the content model diagram
larger.
Schema > View Zoom Out Makes the items in the content model diagram
smaller.
Schema > View Auto-Update Diagram The Auto-Update Diagram feature updates the
content model diagram every time a change is
made. This menu option toggles this feature on or
off.
Schema > View Expand Launches the Content Model Editor, an expanded
dialog box for editing content models. The Content
Model Editor launches only when the cursor is
located within the Content Model column of the
element/type list.
Schema > Tools Check For Errors Checks the DTD for errors and reports the results in
the errors panel. (This function can also be
performed by way of the Errors button on the
toolbar.)
Schema > Tools Define Reusable Provides options for creating either reusable pieces
of declarations or text. For more information on
reusables, see Building Content Models with
Reusables (Internal Parameter Entities), page 91
(DTD).
Schema > Tools Edit Reusable Provides options for editing existing reusable pieces
of declarations or text.
Schema > Tools Find Enables you to search for text in the active window.
or Edit Select this option for the initial search.
Schema > Tools Find Again Searches for the next occurrence of the text
or Edit previously entered in the Find dialog box.
Schema > Tools Replace Used to search and replace text in the active
or Edit window. Replace is used for the initial
search-and-replace.
Schema > Tools Replace Again Searches and replaces the next occurrence of the text
or Edit previously entered in the Replace dialog box.
• The View menu provides options to control the panels used for editing,
organizing, and viewing your XML instance.
• The Presentation menu allows you to associate one or more customized views
with the active instance document. The presentations are associated at the
schema level, so the views you create for a single document adhering to a
schema become available for all instances of the schema.
Table 6 describes the XML menu.
XML > Tools Find Enables you to search for text in the active window.
Select this option for the initial search.
XML > Tools Find Again Searches for the next occurrence of the text previously
entered in the Find dialog box.
XML > Tools Replace Used to search and replace text in the active window.
Replace is used for the initial search-and-replace.
XML > Tools Replace Again Searches and replaces the next occurrence of the text
previously entered in the Replace dialog box.
XML > View Navigator Toggles the navigator bar on or off. If a check appears
to the left of the menu item, the Context bar is turned
on.
XML > View Factory Toggles the factory bar on or off. If a check appears to
the left of the menu item, the factory bar is turned on.
XML > View Errors Opens or closes the errors panel that displays errors
found when validating a document against a schema.
XML > View Markup Icons Toggles on or off the blue markup icons to the
immediate left of items in the tag structure. If a check
appears to the left of the menu item, the option is
turned on.
XML > View Default Attributes Hides or displays any default values specified for
attributes in the schema. If a check appears to the left
of the menu item, the option is turned on.
XML > View Content Displays the content panel. If a check appears to the
left of the menu item, the content panel is displayed.
XML > View Source Displays the source panel. If a check appears to the
left of the menu item, the source panel is displayed.
XML > View Align Choosing this option will left-align all tags and
Labels/Indent markup icons in the tag area. When Align Labels is
Labels active, the View menu selection changes to Indent
Labels. Choosing Indent Labels will return the tag
structure to its default display (with indents).
XML > Presentation New Creates a new presentation. Returns the content view
to its default environment to allow new
customizations from scratch.
XML > Presentation Save As Allows you to name and save the current
presentation.
XML > Presentation (Presentation A listing of the previously defined presentations. The
Listing) presentation currently displayed is indicated by a
check mark.
XML > Presentation Set Default Sets the presentation selected in the presentation
listing as the presentation to appear by default when
its associated schema is initially set.
Element icon
Element content
indicator
Type name
Attribute icon
Elements that are separated by the 'or' symbol ('|') in the content model appear to
the right of the parent element, after two diagonal branch indicators, in the order
they appear in the content model. Figure 7 shows the representation of an element
named c h o i c e s with the content model ( c h o i c e 1 | c h o i c e 2 | c h o i c e 3 ) .
Occurrence indicator symbols are used to identify how often an element may or
must appear and are shown in the content model diagram. If occurrence
indicators apply to a group of elements, the elements are illustrated in the content
model diagram as branching off an occurrence indicator symbol. Figure 8 shows a
content model similar to that presented in Figure 7, but with the group of choices
made optional and repeatable. The m u l t i c h o i c e element has the content model
(choice1 | choice2 | choice3)*.
Mixed declarations always offer a choice of elements that are both optional and
repeatable. These appear as the mixed element shown below in Figure 10. Note
that the m i x e d element may contain both text and elements.
Schema
Resource
The Schema resource of the XML Tools palette enables the creation of an XML
Schema file, as defined by the W3C Recommendation (May 2001).
An XML Schema describes the vocabulary and structures that may appear within
an XML instance document conforming to that schema. Schemas use their own
formal grammars to express document structures and vocabulary. If a set of
documents uses the same schema, the documents may have markedly different
contents, but can share common processing. Applications check documents
against the schema, and process them only if the document passes inspection
(more commonly called validation). By providing a common formal vocabulary
for describing the terms on which information will be exchanged, schemas act as
an easily enforced contract between senders and receivers (and creators and
consumers) of information.
When a Schema resource is selected in your project, a set of new panels, menu
options, and toolbar buttons is provided, helping you build and edit your schema
from a variety of different perspectives. Each panel provides access to a different
set of tools. The multiple panels may show information simultaneously, but all of
them combine to present a consistent view of your schema. This chapter describes
each of the panels in detail.
Configuration Tab
The C o n f i g u r a t i o n tab has the following fields.
Field Description
Name Name of the file when persisted. The * . x s d suffix will be
automatically added.
Field Description
Schema Name Name of the file when persisted. The * . x s d suffix will be
automatically added.
Import Reserved Check this field to import the reserved XML namespace,
XML Namespace enabling the use of the attributes defined within the XML
namespace (x m l : l a n g , x m l : s p a c e , or x m l : b a s e ).
Field Description
elementFormDefault By default, the e l e m e n t F o r m D e f a u l t attribute of the
schema element takes the value q u a l i f i e d . Thus, you
must declare top-level elements to be associated with
a namespace in the instance document.
Field Description
attributeFormDefault By default, the a t t r i b u t e F o r m D e f a u l t attribute of
the s c h e m a element takes the value u n q u a l i f i e d .
Thus, unless you specify otherwise, only globally
declared attributes can be associated with a
namespace in the instance document.
Field Description
Element Type Number of element declarations.
Toolbar
For a description of the buttons that appear on the toolbar when editing Schema
resources, see Toolbar Buttons on page 27.
Schema Menu
A Schema menu becomes available when editing a Schema resource. The Schema
menu contains two submenus, View and Edit.
The View menu provides options to control the panels used for editing,
organizing, and viewing your schemas. The Edit menu includes options for
searching your schema.
The Schema menu options are described in detail in Table 5 on page 29.
Elements/Types Panel
The elements/types panel enables you to view, create, and edit element and
attribute declarations and complex type definitions. The elements/types panel is
typically the place you'll start defining your schemas.
The panel is divided into two parts: a graphical view of the content model (the
content model diagram) and an editable list of element declarations and complex
type definitions and their content models (the element/type list panel). The next
diagram illustrates the element/types panel.
Elements/Types List
The elements/types list, located at the bottom of the elements/types panel, is
where much of the creation and editing of element declarations and complex type
definitions takes place. The next diagram illustrates the element/type list.
Each element and/or complex type is listed in a row of the table. Information that
defines each item appears in columns across the table and includes the following
(from left to right).
Column Description
Row Selector/ This column allows you to modify the row and detect
Error Indicator errors in the declaration. See Common Columns In
Tables on page 26 for more information about this
column.
Declaration Type Click within this column to indicate whether the row
(D) should be used for an element declaration (signified by
an “E”) or a complex type definition (signified by a “T”).
The desired declaration type can be selected by clicking
the Decl Type button.
Column Description
Content The content column is used to specify the type of content
model to be created. When the user tabs to this column, a
C o n t e n t T y p e button appears, providing a menu of the
following choices.
• Any — The content model contains any combination
of elements and/or character data (text).
• E m p t y — When an element has no content at all, its
content model is empty. Essentially, a model is
defined that allows only elements in its content but
does not actually declare any elements, so the type's
content model is empty.
• M i x e d — In a mixed content model, an element
contains other elements interleaved with character
content. Character data can appear alongside child
elements and is not confined to the deepest child
elements.
• Elements — The content model contains elements
only.
• Typed— The content is either a simple type (such as
xs:string, xs:integer, or x s : f l o a t ) or a
named complex type.
Column Description
Content The C o n t e n t M o d e l / D a t a T y p e column displays the
Model/Data Type content model of the elements and provides a set of tools
for creating and editing content models and data types.
(The name of this column is either C o n t e n t M o d e l or
D a t a T y p e , depending on the content type set in the
C o n t e n t column.) Users who are comfortable with
occurrence and sequence indicator syntax can enter
element content models directly by typing them in the
C o n t e n t M o d e l column. For users not yet comfortable
with occurrence and sequence indicators, a series of
buttons are provided to help the user create and edit
content models. See Building Content Models:
Occurrence and Sequence Indicators on page 45 for more
information.
The I n s e r t button provides a drop-down menu that
differs depending on whether the content model may
include elements or data. The I n s e r t menu provides a
quick way to add content that's been previously defined,
such as a built-in data type, a user-defined simple type,
an element, or a complex type. The selected material is
inserted at the current location of the cursor. See
Example: Building a Content Model on page 46 for more
information.
For a description of XML Schema’s built-in data types,
see
http://www.w3.org/TR/xmlschema-2/#built-in-dataty
pes
? The element (or group of elements) may appear zero Optional but not
or one times. The element is optional, but is only Repeatable.
allowed to appear once if used.
+ The element (or group of elements) must appear one Repeatable but not
or more times. The element is required to appear at Optional.
least once, but multiple consecutive occurrences may
be present.
* The element (or group of elements) may appear zero Repeatable and Optional.
or more times. The element can appear as many
times consecutively as needed, or even zero times.
{} The element (or group of elements) must appear {}and specify the min. and
within the specified range of times. max. values for the range.
& Elements may appear in any order, but may not be All
repeatable.
The I n t r o element could appear once (and only once) at the start of the chapter,
and then Section or Sidebar elements could follow in any order. (This model is
read as “an Intro element followed by zero or more Section or Sidebar elements”.)
You will build the content model for an element based on the structure of a book.
The content model would likely include several elements, including a T i t l e , an
A u t h o r, multiple C h a p t e r s , maybe an A p p e n d i x (or several), perhaps a G l o s s a r y,
and possibly an I n d e x . Assuming these elements are already declared (as shown
in the next diagram), the steps to build the content model for B o o k appear below:
1. In the row for B o o k , click in the blank cell under the Content Model column.
This is where the entry for the content model will be created. A series of
buttons will appear.
2. Click the Insert button. A pull-down menu of all the element declarations
within the file appears.
3. Select the first element to be part of the content model (in this case, you’ll start
with T i t l e ). Repeat this step, selecting each element that is part of the content
model. It is best to select the sub-elements in sequence if possible, because as
each sub-element is selected, a comma is inserted between items by default to
indicate that they are in sequence. The sub-element will always be inserted
where the cursor is placed in the content model.
If the elements for the content model have not been previously declared, type
them in within the parentheses. When the content model is completed, you will
be prompted to auto-create (declare) the new elements.
4. Which items may be repeatable? Within a book, the chapters usually occur
more than once, so this sub-element needs to be indicated as a repeatable item.
Highlight C h a p t e r in the Content Model, and click on the Repeatable button.
This adds a '+' indicator after C h a p t e r, to indicate it is repeatable. Likewise,
there may be more than one appendix, so highlight A p p e n d i x and click
Repeatable to add a '+' indicator after A p p e n d i x .
5. Which items are optional? Within a book, a glossary or index may not always
occur, so these sub-elements need to be made optional. Highlight G l o s s a r y,
and click the Optional button. Likewise, highlight I n d e x , and click the
Optional button. This will place a '?' after each of these sub-elements, to
indicate they are optional.
6. Appendix is also an optional item (not all books have appendices). Highlight
Appendix and click the Optional button. Because Appendix is now both
optional and repeatable, it is indicated with an '*' after it. Press the <Enter>
key or click anywhere else in the element list to complete the content model
definition.
• The {} button, which is used to set specific occurrence ranges for repeatable
elements.
Attributes Panel
When you select the Schema > View > Attributes menu, or when you click the
Attributes button on the toolbar, the attributes panel becomes the primary panel
for editing. The attributes panel is used to view, create, and edit attribute type
declarations. While you can also create an element’s attribute in the element/type
list, you must use the A t t r i b u t e s panel to specify an attribute’s data type.
Constraints, facets and enumeration of attributes are set from the properties panel
when the attribute is selected.
Figure 16 illustrates the attributes panel.
Each attribute is listed in a row of the panel. Information associated with each
attribute appears in columns across the panel and includes the following (from
left to right).
Column Description
Row This column allows you to modify the row and detect
Selector/Error errors in the declaration. See Common Columns In
Indicator Tables on page 26 for more information about this
column.
Column Description
Element The Element column lists the element to which an
attribute belongs. You can enter the element to which an
attribute belongs by typing its name in the element
column.
New attributes entered in the element/type list of the elements/types panel are
automatically created in the attributes panel with a data type of x s : s t r i n g .
Creation of an attribute type within the attributes panel consists of several steps.
As an example, let's say we have an element P i c t u r e , with the attribute
G r a p h i c s T y p e . G r a p h i c s T y p e is an attribute that tells us if a picture is a JPG, TIF,
or GIF file.
To declare an attribute, follow these steps:
1. Create an element named Picture, assign it the Elements content type and
create an attribute by typing GraphicsType in the Attributes column.
Names must begin with a letter and may contain numbers, underscores,
dashes, and full stops -- typically periods.
An attribute type declaration, by default, sets the data type for an attribute to
xs:string. In this example, G r a p h i c s T y p e will be enumerated (that is, it will
only ever have the value of J P G , T I F, or G I F ). Because the values for this
enumeration are best defined as strings, the x s : s t r i n g data type is
appropriate. An attribute type declaration, by default, sets the data type for an
attribute to x s : s t r i n g . In this example, G r a p h i c s T y p e will be enumerated
(that is, it will only ever have the value of J P G , T I F, or G I F ). Because the values
for this enumeration are best defined as strings, the x s : s t r i n g data type is
appropriate. For example:
4. A default value can be entered for an attribute. The value must have been
defined under the Enumerations tab. For example, to set the default value of
GraphicsType to J P G , click the Properties tab and enter JPG in the default
field.
Overview Panel
When selected from the Schema > View menu or upon clicking the Overview
button on the toolbar, the overview panel loads to the left of the elements/types
panel. The overview panel allows you to control the creation of schemas that use
imports and includes, as well as explore the overall organization of your schema.
The overview panel's tools let you build schemas from declarations in multiple
files, creating large composite schemas from sets of smaller ones, enhancing
reusability and simplifying management.
Figure 17 illustrates the overview panel, with a right button menu activated.
Overview Tree
The overview panel provides a tree-like overview of the schema structure. Each
schema component type is represented by an icon, described in the table below.
attribute
namespace
complex type
model group
attribute group
XML comment
schema document
included schema
A right menu button is provided for each component in the overview tree. From
the menu, you can cut, copy, paste or delete a declaration or module (removing it
or changing its location in the schema). There is also an option to “Go to” or
“Edit” the component, which will take you to an area to edit the selected item.
If the declaration is located in an external schema that has been added to the
current schema, a menu option to unlock the module is provided. Before any edits
can be made to included declarations (identified by a document icon with a red
slash), the included schema must be unlocked. When a module is unlocked, the
red line disappears from the document icon. When you're done editing the
included declarations, you can right-click on the module and lock it again .
Import Button
The Import button of the overview panel allows you to import the namespace of
another schema in your project, making the components defined in the other
schema that can be referenced in your schema. To remove a namespace, right click
on the namespace (labelled with the namespace’s prefix) and select Delete from
the pop-up menu that appears.
2. Browse to and select the schema containing the components you would like to
reference.
The imported namespace will appear as an icon in the overview panel’s tree
and as an entry in the N a m e s p a c e s tab of the advanced panel.
3. The components (elements, attributes, complex types, and user-defined
simple types) from the imported namespace can now be referenced within the
content models of your schema. When referencing components from other
namespaces, be sure to use the prefix for the external namespace. In Figure 18,
an a d d r e s s element defined in a different namespace is being used within the
content model for a s h i p - t o element.
The prefix used to associate components with the namespace can be changed in
the N a m e s p a c e s tab of the A d v a n c e d panel.
Include Button
The Include option of the overview panel allows you to include the declarations
from another of your project’s schemas into the schema you are currently
building. To remove an included schema, right click on the included schema icon
and select Delete from the pop-up menu that appears.
An included schema must belong to the same target namespace as the including
schema or to no namespace (in which case it becomes part of the including
schema’s namespace). If the external schema’s namespace differs from the schema
you are building, consider reusing its components through the Include option
described above.
Properties Panel
When selected from the Schema > View menu or upon clicking the Properties
button on the toolbar, the properties panel loads to the left of the elements/types
panel. The properties panel includes three tabs:
• Select the Properties tab to specify advanced properties on the selected
declaration. For more information this tab, see Properties Tab.
• Select the Facets tab to apply facets that constrain the value of a data type. For
more information on this tab, see Facets Tab on page 61.
• Select the Enumeration tab to create a list of acceptable values for the specified
data type. For more information on this tab, see Enumeration Tab on page 62.
Properties Tab
The Properties tab is accessed by clicking the Properties button on the toolbar. The
Properties tab is used for setting and viewing component level properties. The
properties control how the component can be used within the Schema or within
an XML instance document.
The Properties tab becomes active when an element, complex type, attribute, or
Simple type declaration (row) is selected in its respective panel. The fields
available within the P r o p e r t i e s tab, summarized Table 9 below, vary depending
on the selected declaration type.
Field Description
id Use the id field to add an identifier to the selected component
declaration.
Field Description
block Use the b l o c k property to control whether types can be
replaced by their derived types in instance documents. The
b l o c k property takes one of the following values:
Field Description
default Use this field to specify a default value for the selected element
or attribute declaration. If the element or attribute appears in an
XML instance, it can have any value that corresponds to the
data type. If the element or attribute does not appear, the
schema processor will assign the element or attribute's value to
be what you've specified in this field.
fixed Use this field to specify a fixed value for the selected element or
attribute declaration. If the element or attribute appears in an
XML instance document, it must match the value you've
specified in this field. If the element or attribute does not
appear, the schema parser will assign the element or attribute’s
value to be what you've specified in this field.
The settings in the Properties tab apply to the selected component only. To apply
similar properties to all instances of a component type in the schema, use the
Attributes tab of the configuration panel. See Schema Properties Panel on page 38
for more information.
Facets Tab
The Facets tab is used to further constrain the acceptable values for your schema’s
components by applying facets to your simple types (data types). Accordingly,
the Facets tab becomes applicable when a declaration uses a simple type, such as
a text-only element declarations, attribute declarations, and user-derived data
type definitions.
When constraints are applicable, the Facets tab can be accessed by:
• clicking the Properties button on the Toolbar and then clicking the Facets tab
of the properties panel.
• clicking the Facets button in the Simple types column of the elements/types
panel.
• clicking the Facets button in the Base type column of the Simple types panel.
• clicking the Facets button in the Data type column of the attributes panel.
The constraining facets available within the Facets tab, summarized in the table
below, vary depending on the type of data type being used.
Facet Description
Make list Check this option if a white space separated list of values
(corresponding to the data type) is desired.
Facet Description
whiteSpace Specifies how white space should be handled in the type’s
value. A menu offering the options to collapse, preserve, or
replace white space is provided.
Enumeration Tab
The Enumeration tab allows you to enumerate allowable values of a specified
simple type (data type). Accordingly, the Enumeration tab becomes applicable
when a declaration uses a simple type, such as a text-only element declarations,
attribute declarations, and user-derived data type definitions.
Advanced Panel
When you choose the Schema > View > Advanced menu, the advanced panel
becomes the primary panel for editing. The advanced panel allows you to define
or edit parts of XML schemas that move beyond the description of document
structures. The advanced panel consists of three tabs.
• Namespaces Tab
• Notations Tab
Namespaces Tab
The N a m e s p a c e s tab provides an inventory of the external namespaces being used
by your schema. The X M L S c h e m a namespace (unless designated as the default
namespace) and any namespaces added by way of the Import button of the
overview panel will appear in the N a m e s p a c e s tab.
The N a m e s p a c e s tab permits only limited editing of the namespace declaration:
• the imported namespace can be removed using the row selector
• the prefix can be changed
The Namespaces tab cannot be used to add a new namespace or change the URI
or location for an existing namespace. These operations must be performed
within the overview panel.
Each namespace is listed in a row of the panel. Information associated with each
namespace appears in columns across the panel and includes the following (from
left to right):
Column Description
Row Selector/Error Allows you to modify the row and detect errors in the
Indicator declaration. See Common Columns In Tables on page 26.
Column Description
Included Document Indicates whether the declaration comes from the file
Indicator being edited or from an external schema. See Common
Columns In Tables on page 26.
Prefix Enter or edit the prefix for the namespace. The prefix is
used to link a component with its namespace and to
distinguish the component throughout the body of the
schema from those components defined in other
namespaces. Typically the prefix represents an
abbreviation for the type of document contained in the
namespace.
The target namespace for your schema will not be displayed in the Namespaces
tab. Target namespace information is available in the Target Namespace tab of the
Schema Properties panel.
Notations Tab
Notations allow you to describe a new data type or file type. The description
involves a name for the type and a link to more information on the type or to
programs that can process the type. For example, the notations declared in
Figure 19 provide information on ISO8601 dates and times, and Java integers.
Either could be used for a data type and will appear as an option in the type
menus that appear in the elements panel and attributes panel.
Each notation is listed in a row of the panel. Information associated with each
notation appears in columns across the panel and includes the following (from
left to right).
Column Description
Row Selector/Error This column allows you to modify the row and detect
Indicator errors in the declaration. See Common Columns In
Tables on page 26 for more information about this
column.
Location Enter the URL that will serve as the system identifier
for the notation. System identifiers are not required
for notations, though at least one identifier (system or
public) must appear. System identifiers may point to
standards describing the content, or to programs that
can actually process it.
Each simple type is listed in a row of the panel. Information associated with each
simple type appears in columns across the panel and includes the following (from
left to right).
Column Description
Row Selector/Error Allows you to modify the row and detect errors in the
Indicator declaration. See Common Columns In Tables on
page 26.
Included Document Indicates whether the declaration comes from the file
Indicator being edited or from an external schema. See
Common Columns In Tables on page 26.
Column Description
Base Type The Base Type field indicates the existing simple type
you would like to constrain to create the new simple
type. To specify a base type, click the Type button in
the Base Type column and choose a type from the
drop-down menu of built-in types.
Note: For a description of XML Schema’s built-in data
types, see
http://www.w3.org/TR/xmlschema-2/#built-in-dat
atypes
User-defined types, such as r a t i n g , can also be used
as base types. To further constrain r a t i n g , use the
Insert user-defined type button within the Base Type
column.
Once a new simple type has been defined, it becomes a choice in the Insert menus
of the elements/types panel and attributes panel, when appropriate.
2. Tab to the Base Type field and use the N a t i v e Type button to select the type
x s : p o s i t i v e I n t e g e r.
3. Click the Facets button, which loads the Facets tab of the properties panel.
4. In the properties panel, use the m i n I n c l u s i v e and m a x I n c u s i v e facets to
restrict the acceptable values of rating to positive integers from 1 to 10.
The r a t i n g type is now declared and will become a choice on the User
Defined Type menu available in the elements/types panel, the attributes
panel, and the simple types panel.
The name for your schema can only be specified in the configuration panel.
Validations Panel
When selected by way of the Schema > View > Validation menu, the validation
panel appears between the active editing panel and the configuration panel. The
validation panel displays errors or warnings found when a new schema is loaded,
as well as errors or warnings detected throughout the editing process.
The validations panel indicates the total number of errors or warnings and
provides a list of errors and details about the errors in this panel. Clicking on the
error message will take you to the source of the error.
To update validation information in the schema after correcting an error, it's good
practice to reevaluate again by way of the Revaluate button on top of the panel.
When the Component Doc panel reflects the selected declaration, the following
tabs are available:
Tab Description
Documentation Use this tab to associate a new note with the selected
declaration. In the source code, the note will appear
within the selected declaration.
Source Preview Displays the source code for the selected declaration.
Source Panel
When selected by way of the Schema > View > Source menu or upon clicking the
Source button on the toolbar, the source panel becomes the primary panel for
editing. The source panel allows you to edit the source code of your Schema
directly. If you are comfortable with Schema syntax, editing your declarations
directly may occasionally be useful or even convenient. Even if you don't want to
edit your Schemas directly, the source panel provides another way to examine
your declarations.
To make the other panels reflect the changes you've made, click Reparse at the top
of the panel. Any errors found upon reparse will be listed in the Validation panel.
To help you become familiar with the panels available when working with
Schema resources, we have included two step-by-step exercises. The first exercise
walks you through the creation of a simple schema, introducing you to the
fundamental features of the editing environment. The second exercise introduces
some more advanced concepts, notably the creation and implementation of
complex and simple types. Each example should take about 15-20 minutes to
complete.
Component Description
price.list the “root” element inside of which all others will appear
Getting Started
To create the project and the manufacturer schema:
1. In the project panel, create, then select a project folder named QuickTour.
2. Drag a Schema icon from the XML Tools palette into the design panel. This
creates a Schema resource.
3. Double click the Schema resource in the design panel.
A series of new panels will appear.
4. Resize the panels, so that the elements/types panel is prominently displayed.
The elements/types panel presents an inventory of all of the elements and
complex types allowed within a document conforming to this schema. The
elements/types panel consists of the content model diagram (upper half) and
the element/type list (lower half). The element/type list, where most of the
work in this exercise will be performed, has a tabular format, with the fields in
each row identified by column headings.
5. To define the manufacturer root element, follow these steps:
a. In the Element column, select r o o t and replace it with m a n u f a c t u r e r .
b. Tab across to the Attributes column and type in n a m e . Here you can define
attributes for an element. When entering multiple attributes, commas
should separate them.
You can navigate around the tables in each panel by using ENTER, TAB,
SHIFT-ENTER, and SHIFT-TAB.
6. To create the next element, move your cursor to the row below m a n u f a c t u r e r
and type d a t e . i s s u e d .
c. Tab to the next field. (Notice that the column heading changes from
“Content Model” to “Data Type”.) To provide the d a t e . i s s u e d element
with an appropriate data type, select d a t e from the menu that appears
upon clicking Insert.
8. To specify that the m a n u f a c t u r e r element must always include the
d a t e . i s s u e d element
When adding elements to a content model (within the “Content Model” column),
if your input exceeds the column width, type Ctrl+E or select “Expand” from the
Schema>View menu to open a larger window for editing the selected area.
3. Tab from this field. The Auto Create dialog box appears. Click the Globally
defined button, then click Create. (For the purposes of this exercise, all
declarations will be global.)
4. As it is currently defined, all elements are required. At times, you may want
an element to be optional. For the purposes of this exercise, make
d e s c r i p t i o n an optional element:
To further refine the definitions of these attributes, you can right-click on each
of their names and choose “Go to < n a m e > “or click Attributes on the toolbar.
The attributes panel will appear with options for data typing the attribute and
for indicating its usage (o p t i o n a l , r e q u i r e d , d e f a u l t , f i x e d , o r
p r o h i b i t e d ).
8. Within the attributes panel, indicate that the values of the s t a r t . d a t e and
e n d . d a t e attributes should be of type d a t e .
You can use the navigation buttons on the toolbar or the Schema>View menu to
open and close between the editor's panels.
XML schemas typically have a single root element that contains all other
elements. In this schema, our root element will be called p r i c e . l i s t .
1. Return to the elements/types panel and add an element named p r i c e . l i s t .
Press tab and specify “Elements” content.
2. Enter m a n u f a c t u r e r , p r o d u c t + as the content model. (The plus sign
designates the p r o d u c t element as required and repeatable.) Tab out of the
field to update the schema.
The Apply button makes the file available to other resources in the project. The
schema is saved when the entire project has been saved.
Graphical view
By defining content models, a structure for the document is established. This
structure can be thought of as a tree where the “root” is the encompassing
element and its branches are the elements and attributes that may be contained
within it (as defined by the content model). In turn each branch may have
branches defined by their content model. The diagram at the top of the elements/
types panel provides a graphical view of these relationships. Explore the content
model by clicking on the elements to expand and collapse their content.
(Specifically click on the Element Content Indicator icon, labeled in Figure 21 on
page 75.) Only elements that define a content model can be expanded. Within the
diagram, double clicking on the root element, in this case p r i c e . l i s t , will
produce a graphical view of the entire schema.
The diagram for the price list schema is shown in Figure 21.
Element
Content
Indicator
For each element and attribute in the diagram, a right button menu offering key
editing functions is provided. Right-click the background to zoom in or out of the
diagram as a whole.
Source view
To view the actual schema syntax for the schema you've created, open the source
panel by clicking on the source panel icon on the main toolbar. The notes panel,
which allows you to enter supplemental information about any element or
attribute, also allows you to view the source for individual declarations. Open the
notes panel using the Schema menu (Schema > View > Notes). Click on the
“Source Preview” tab at the bottom of the notes panel to view the source for the
element declaration currently selected in the element list.
Conclusion
Congratulations! You have completed the exercise. This tutorial introduced the
basic steps required to create an XML Schema. Exercise 2: Defining and Deriving
Complex and Simple Types on page 76 will teach you how to create and use your
own complex and simple types.
To learn how to build a sample XML document based on the schema you have
just built, see XML Instance Exercise on page 137.
Component Description
Address Complex type from which two other complex types are
derived
Component Description
postcode Element for the UK postal code
Getting Started
1. In the project panel, create and select a project folder named QuickTour.
2. To create a new Schema resource, drag a Schema icon from the XML Tools
palette into the design panel.
3. Within the design panel, double click the schema icon. A series of new panels
will appear. Resize the panels, such that the elements/types panel is
prominently displayed. The elements/types panel presents an inventory of all
of the elements and complex types allowed within a document conforming to
this schema. The elements/types panel consists of the content model diagram
(upper half) and the element/type list (lower half). The element/type list,
where most of the work in this exercise will be performed, has a tabular
format, with the fields in each row identified by column headings.
4. To create a new complex type, click in the first field of the second row (under
column “D”). The field initially displays an “E”, an indication that the row is
used for an element declaration. To use the row for a complex type definition,
click Decl Type and choose “T” from the menu.
5. Tab to the adjacent empty field in the second column, and type in A d d r e s s as
the name of the complex type. Tab to the “Derives From” column. Notice that
the second column's heading has changed from “Element” to “Complex
Type”.
6. Later in this exercise you'll use the “Derives From” column to extend the
A d d r e s s complex type. For now, however, we can bypass this field, and tab to
the Content field. The content will default to “Elements”, which is the desired
content. (Other content types could be selected by way of the menu presented
by clicking the Content Type button.)
7. Tab to the Content Model field. With the pointer positioned between the
parentheses, type in the following elements, separated by commas: n a m e ,
s t r e e t , c i t y.
8. Tab from the “Content Model” field. The Auto Create dialog box appears.
Indicate that the new elements should be Globally defined and then click
Create. (For the purposes of this tutorial, all declarations will be global.)
Before you continue to build the address schema, save your progress to this
point. In the configuration panel, name your schema “address”. You should
also specify a target namespace to differentiate this schema from all others.
The Target Namespace field will be pre-populated with a randomly generated
namespace. Change this namespace to reflect a URL meaningful to your
organization. Finally add a prefix, such as “addr”, to be used to indicate that
the components you are defining belong to your namespace. Click Apply.
The Apply button makes the file available to other resources in the project. The
schema is saved when the entire project has been saved.
Follow the same procedure for the values 'AL' and 'AR'. (Of course, there are
more postal abbreviations, but let’s stop here.)
5. Tab to the Content column and make sure element content is reflected.
(Elements should be pre-selected as the most appropriate model).
6. Tab to the Content Model column. Inside the parentheses, type s t a t e , zip.
Tab out of the Content Model column.
7. In the Auto-Create dialog box that appears, click the G l o b a l l y defined radio
button and then click Create.
8. In the row for the element s t a t e , navigate to the Data Type column. Click
Insert user-defined type and select U S S t a t e from the menu of options.
9. In the row for the element z i p , click in the Data Type column. Click Insert to
display a menu of XML Schema data types. Choose “More” on this menu to
display a submenu. Choose p o s i t i v e I n t e g e r as the data type for z i p .
You are now ready to define some elements on your own.
1. Define a complex type named U K A d d r e s s as an extension of A d d r e s s . Add the
element p o s t c o d e to the content model and create p o s t c o d e as a global
declaration. Also give U K A d d r e s s and attribute called e x p o r t C o d e .
2. For further practice, define a simple type (data type) called U K P o s t c o d e and
assign it to the p o s t c o d e element. The new simple type can be an extension or
restriction of an existing simple type. For example, to be very precise, you
could restrict a string by specifying a regular expression (pattern) that the type
must match.
The address types created in this schema could later be applied to elements. For
example, s h i p T o and b i l l T o elements could be added to this schema and be
declared as having the type U S A d d r e s s . These type definitions could also be used
in other schemas. As a final exercise, create a new schema resource and import the
address schema namespace you created in this tutorial. The easiest way to import
a namespace is to use the Add Namespace option of the overview panel, which
enables you to browse and select another schema from your project. Once the
address schema created in this exercise has been imported, create a s h i p T o of
Conclusion
This exercise serves as an introduction to XML Schema design. Review the
documentation to learn more about XML Schema functionality and to facilitate
your implementation of advanced features.
DTD
Resource
The DTD resource of the XML Tools palette enables the creation of a DTD
(Document Type Definition), as defined by the W3C’s XML 1.0 Recommendation.
A DTD shares the same role as an XML Schema, describing the vocabulary and
structures that may appear within an XML instance document. While DTDs are
supported in XML 1.0-compliant parsers and applications, they offer very limited
data typing and are considered the 'first generation' of XML schemas.
When a DTD resource is selected in your project, a set of new panels, menu
options, and toolbar buttons are provided, helping you build and edit your DTD
from a variety of different perspectives. Each panel provides access to a different
set of tools. The multiple panels may show information simultaneously, but all of
them combine to present a consistent view of your schema. This chapter describes
each of the panels in detail.
Configuration Panel
When editing a DTD resource, the configuration panel provides two tabs for
setting or viewing high-level properties.
Configuration
The Configuration tab has the following fields.
Field Description
Name This is the name of the file when persisted. The * . d t d suffix
will be automatically added.
Statistics
The Statistics tab is not editable. The tab displays the number of times a schema
component type is used. The Statistics tab has the following fields.
Field Description
Elements The number of element declarations is displayed.
Field Description
Complex Types The number of complex type definitions is
displayed. (This is an XML Schema metric only.)
Toolbar
For a description of the buttons that appear on the toolbar when editing DTD
resources, see Toolbar Buttons on page 27.
Schema Menu
A Schema menu becomes available when editing a DTD resource. The Schema
menu contains two submenus, View and Tools.
The View menu provides options to control the panels used for editing,
organizing, and viewing your schemas. The Tools menu includes options for
searching or editing your schema, checking your schema for errors, and defining
reusable schema components.
The Schema menu options are described in Table 5 on page 29.
Elements Panel
The elements panel enables you to view, create, and edit element and attribute
declarations. The elements panel is typically the place you'll start defining your
schemas.
The panel is divided into two parts: a graphical view of the content model (the
content model diagram) and an editable list of element declarations and their
content models (the element list).
Column Description
Row This column allows you to modify the row and detect errors
Selector/Error in the declaration. See Common Columns In Tables on
Indicator page 26 for more information about this column.
Column Description
Content The content column is used to specify the type of content
model to be created. When the user tabs to this column, a
Content Type button appears, providing a menu of the
following choices.
• ANY — The content model contains any combination of
elements and/or character data (text).
• EMPTY — When an element has no content at all, its
content model is empty. Essentially, a model is defined
that allows only elements in its content but does not
actually declare any elements, so the type's content model
is empty.
• Mixed — In a mixed content model, an element contains
other elements interleaved with character content.
Character data can appear alongside child elements and is
not confined to the deepest child elements.
• Elements — The content model contains elements only.
• Text — The content model contains only character data
(text). A character-only element can represent an atomic
data type whose value is encoded as character data.
• Type — Data types that constrain text -- like i n t e g e r or
d a t e -- are not afforded by DTDs. Accordingly, selecting
the Type option is equivalent to selecting the Text option.
Column Description
Content The Content Model column displays the content model of the
Model elements and provides a set of tools for creating and editing
content models.
Note: If text is selected as content, the name of this column
switches to Data Type, to indicate that the element content is
text. The Data Type column should remain empty when text
is the specified content.
Users who are comfortable with occurrence and sequence
indicator syntax can enter element content models directly by
typing them in the Content Model column. For users not yet
comfortable with occurrence and sequence indicators, a series
of buttons are provided to help the user create and edit
content models. (See Building Content Models: Occurrence
and Sequence Indicators on page 87 for more information.)
The Insert menu provides a quick way to add elements (or
internal parameter entities representing element content) that
have been previously defined. The selected item is inserted at
the current location of the cursor. (See Example: Building a
Content Model on page 88 and Building Content Models with
Reusables (Internal Parameter Entities) on page 91 for more
information.)
Note: To create a reusable model group (internal parameter
entity representing element content), choose Create Model
Group... from the Insert drop-down menu. Alternatively,
parameter entities can be defined and edited by way of the
Schema>Tools menu.
The element list can be sorted at any time by clicking on one of the column
headers. For example, to sort the list by the name of the element, click on the
Element column header. Or, to sort the list by content model, click on the Content
Model column header, and so forth. Shift-clicking on a column header sorts the
column in descending order.
The I n t r o element could appear once (and only once) at the start of the chapter,
and then S e c t i o n or S i d e b a r elements could follow in any order. (This model is
read as “an I n t r o element followed by zero or more S e c t i o n or S i d e b a r
elements”.)
You will build the content model for an element based on the structure of a book.
The content model would likely include several elements, including a T i t l e , an
A u t h o r, multiple C h a p t e r s , maybe an A p p e n d i x (or several), perhaps a G l o s s a r y,
and possibly an I n d e x . Assuming these elements are already declared, the steps
to build the content model for Book appear below:
1. In the row for B o o k , click in the blank cell under the Content Model column.
This is where the entry for the content model will be created. A series of
buttons will appear. You should see the text cursor blinking inside the
parentheses.
2. Click the Insert button. A pull-down menu of all the element declarations
within the file appears.
3. Select the first element to be part of the content model (in this case, we'll start
with T i t l e ). Repeat this step, selecting each element that is part of the content
model. It's best to select the sub-elements in sequence if possible, because as
each sub-element is selected, a comma is inserted between items by default to
indicate that they are in sequence. The sub-element will always be inserted
where the cursor is placed in the content model.
If the elements for the content model have not been previously declared, type
them in within the parentheses. When the content model is completed, you will
be prompted to auto-create (declare) the new elements.
4. Which items may be repeatable? Within a book, the chapters usually occur
more than once, so this sub-element needs to be indicated as a repeatable item.
Highlight C h a p t e r in the Content Model, and click on the Repeatable button.
This adds a '+' indicator after C h a p t e r, to indicate it is repeatable. Likewise,
there may be more than one appendix, so highlight A p p e n d i x and click
Repeatable to add a '+' indicator after A p p e n d i x .
5. Which items are optional? Within a book, a glossary or index may not always
occur, so these sub-elements need to be made optional. Highlight G l o s s a r y,
and click the Optional button. Likewise, highlight I n d e x , and click the
Optional button. This will place a '?' after each of these sub-elements, to
indicate they are optional.
6. Appendix is also an optional item (not all books have appendices). Highlight
Appendix and click the Optional button. Because Appendix is now both
optional and repeatable, it is indicated with an '*' after it. Press the <Enter>
key or click anywhere else in the element list panel to complete the content
model.
This example did not require the use of the Choices button, which indicates
choices between several sub-elements (sub-elements are separated by an '|'
indicator).
When defining new reusables, four editors, described in the table below, are
accessible by way of the Schema menu (Schema > Tools > Define Reusables). For
each editor, you enter the name of the reusable in the text box at the top of the
window, and its content in the large text area.
While you can edit reusables directly in the Parameter Entities Tab of the
advanced panel, it is generally safer to use the reusable editors, especially for
attribute sets. Direct editing is acceptable, but you'll need a firm understanding of
XML 1.0 DTD syntax.
Once your reusables are created, they become available as choices by way of the
Insert button within the Content Model and Attributes column of the element list.
Notice that parameter entities, when referenced, are prepended with a ’ % ’ .
Figure 25 illustrates the use of a reuseable within a content model.
To edit or delete an existing group definition, select the Edit Reusables option of
the Schema menu (Schema > Tools > Edit Reusable).
Attributes Panel
When selected from the Schema > View menu or upon clicking the Attributes
button on the toolbar, the attributes panel becomes the primary panel for editing.
The attributes panel is used to view, create, and edit attribute type declarations.
While you can also create an element’s attribute in the element list, the attributes
panel is required to specify an attribute’s data type, edit its constraints, indicate its
use, and set a default value. The attributes panel is shown in Figure 26.
Each attribute is listed in a row of the panel. Information associated with each
attribute appears in columns across the panel and includes the following (from
left to right).
Column Description
Row This column allows you to modify the row and detect
Selector/Error errors in the declaration. See Common Columns In Tables
Indicator on page 26 for more information about this column.
Column Description
Data Type Attributes have much simpler content model choices than
elements. You can enter an attribute's data type in the Data
Type column by typing it or by clicking the Type button
and then choosing a data type from the list. The available
data types are described in Table 12 on page 97.
Use The Use column lets you indicate how attributes will be
used in XML instance documents. Clicking the Select Use
button will enable you to select from the following options:
• optional — Attribute may appear in an XML instance
document, but its use is not mandatory. No value is
assigned in the schema, but XML document authors
can assign any value to the attribute consistent with its
type.
• required — Attribute must appear once in an XML
instance document. No value is assigned in schema, but
XML document authors can assign any
type-compatible value.
• default — Attribute may appear in an XML instance
document, but its use is not mandatory. If it appears, it
can have any type-compatible value. If the attribute
does not appear, a schema-aware processor will assign
the attribute's value to be what you've specified in the
Value column.
• fixed — Attribute may appear in an XML instance
document, but its use is not mandatory. When present,
the attribute must have the value you've specified in the
Default column. If the attribute does not appear,
schema-aware processors will assign the attribute's
value to be what you've specified in the Value column.
Column Description
Value If the attribute’s usage is designated as d e f a u l t or f i x e d ,
enter the default or fixed value in the Value column.
Choosing either o p t i o n a l or r e q u i r e d and then entering a
value in the Value column will produce an error message.
Choosing either d e f a u l t or f i x e d and omitting a value in
the Default column will also produce an error.
Datatype Meaning
ID The value must be an XML name, beginning with a letter and
otherwise composed of letters, digits, hyphens, underscores,
and full stop characters. (Colons are prohibited for
documents conforming to the Namespaces in XML 1.0 W3C
Recommendation.) The value of the attribute must also be
unique within the document among all attributes of type ID.
ID attributes may never have fixed default values. Only one
attribute per element may be of type ID. Typically, attributes
containing ID values are named 'id', though this is not
required.
Datatype Meaning
NMTOKENS Like NMTOKEN, except that multiple name values may
appear with white space separating the values. (Colons are
prohibited within the value of this type of attribute for
documents conforming to the Namespaces
recommendation.)
DTD data types are not oriented toward data in the sense used by programmers
and database developers, but can be useful for describing relationships within
documents and for constraining data to a list of acceptable values. If you require
stricter, data-oriented data types, consider using Schema resources.
New attributes entered in the element list of the elements panel are automatically
created in the attributes panel with a data type of s t r i n g .
Creation of an attribute type within the attributes panel consists of several steps.
For example, assume you have an element P i c t u r e , with the attributes
G r a p h i c s T y p e . G r a p h i c s T y p e is an attribute that tells us if a picture is a JPG, TIF,
or GIF file. Here are steps for declaring G r a p h i c s T y p e :
1. Click on a blank line under the Attributes Name column. Enter the attribute
name G r a p h i c s T y p e . Names must begin with a letter and may contain
numbers, underscores, dashes, and full stops -- typically periods.
2. Select the cell under the next column heading, Element, in the row for
G r a p h i c s T y p e . Since we know this attribute will be used by the element
P i c t u r e , type in P i c t u r e .
3. Select the cell under the next column heading, Data Type.
An attribute type declaration, by default, sets the data type for an attribute to
s t r i n g . In this example, G r a p h i c s T y p e will be enumerated (that is, it will
only ever have the value of J P G , T I F, or G I F ).
4. Click the Type button and select e n u m e r a t i o n from the XML Types menu.
Since G r a p h i c s T y p e can be only be a J P G , T I F, or G I F, these values must be
entered in the attribute type declaration.
5. Click on the cell under the column heading Constraints, then click on the Edit
Enums button to display the properties panel, with the Enumeration tab
active.
6. In the text box at the top, enter 'JPG' (without quotes), and then click the Add
button.
7. Follow the same procedure to add 'TIF' and 'GIF'.
As you enter values in the Enumeration tab, they are inserted in the
Constraints column of the attributes panel. Notice that the JPG, TIF, and GIF
entries are separated by the OR indicator ('|').
A default value can be entered for an attribute.
8. To set the default value of G r a p h i c s T y p e to J P G , tab into the cell under the
Use column for the row GraphicsType. Click the Select Use button to display a
menu of choices. Choose 'default' from the drop-down menu.
9. Tab to the Value column and enter the default value, which should match one
of the enumerated values.
This completes the declaration for G r a p h i c s T y p e .
Overview Panel
When you choose Schema >View >Overview or click the Overview button on the
toolbar, the overview panel loads to the left of the elements panel. The overview
panel allows you to control the creation of schemas that use multiple modules, as
well as explore the overall organization of your schema. The overview panel's
tools let you build schemas from declarations in multiple files, create large
composite schemas from sets of smaller ones, enhance reusability and simplify
management. Figure 27 illustrates the overview panel with the right button menu
activated.
Overview Tree
The overview panel provides a tree-like overview of the schema structure. Each
schema component type is represented by an icon, described in the table below.
attribute
XML comment
schema document
A right-button menu is provided for each component in the overview tree. From
the menu, you can cut, copy, paste or clear a declaration or module (removing it
or changing its location in the schema). There is also an option to “Go to” or
“Edit” the component, which will take you to an area to edit the selected item.
If the declaration is located in an external schema that has been added to the
current schema, a menu option to unlock the module is provided. Before any edits
can be made to included declarations (identified by a document icon with a red
slash), the included schema must be unlocked. When a module is unlocked, the
red line disappears from the document icon. When you are done editing the
included declarations, you can right-click on the module and lock it again. .
Add Module...Button
The Add Module option of the overview panel allows you to include the
declarations from another of your project’s schemas into the schema you are
currently building (through an external parameter entity reference). To remove an
included schema, right click on the included schema icon and select Clear from
the pop-up menu that appears.
Modules can also be added using the Parameter Entities tab of the advanced
panel.
3. The included schema’s declarations now appears in the declaration panels for
your current schema and can be used just like any other declaration. The
added declarations are not editable by default, however. To edit these
declarations, right click the document icon and choose unlock. Be aware,
however, that any changes made to the declarations will be reflected in the
original document as well.
Properties Panel
When selected from the Schema > View menu or upon clicking the Properties
button on the toolbar, the properties panel loads to the left of the elements panel.
The properties panel includes three tabs -- Properties, Constraints, and
Enumeration. When working with a DTD resource, only the Enumeration tab is
applicable. When an attribute is of type e n u m e r a t i o n , use the Enumeration tab to
create a list of possible values.
Enumeration tab
The Enumeration tab allows you to enumerate allowable values for an attribute.
Accordingly, the Enumeration tab becomes applicable when an attribute is
declared to be of type e n u m e r a t i o n . The Enumeration tab is shown in Figure 28.
Advanced Panel
When selected from the Schema > View menu, the advanced panel becomes the
primary panel for editing. The advanced panel allows you to define or edit parts
of a DTD that move beyond the description of document structures. The
advanced panel consists of the Parameter Entities tab, the General Entities tab, the
Notations tab, and the Processing Instructions tab.
Once you have created a parameter entity, you can reference it within other
declarations. To use parameter entity content, simply reference the entity using
the following syntax:
%entityName;
In the System column, you can use the Insert File Name button to browse for and
select a file in your project containing the desired declarations.
General Entities
DTDs provide facilities for defining some forms of content as well as document
structure. Documents can include this predefined content by reference, allowing
schema developers to centralize management of content as well as structure.
Typically this approach is used to avoid search-and-replace on content that will be
changing, or to include large chunks of 'boilerplate' content within a document.
In the General Entities tab of the advanced panel, the following types of entities
can be defined:
• internal general entities
• external general entities
• external unparsed entities
The top panel is used to define internal general entities, while the bottom panel is
used to define external general entities and unparsed entities.
Like the other panels, the rows begin with a selector button that can be used to
select the entire row for cut, copy, paste, and clear operations. If there is an error in
the declarations made in a row, the row selector button will turn red. The column
between the selector and the entity name will contain a document icon if the
declaration has been included from another file. If it came from another file, it
cannot be edited, though it can be copied and pasted into the current file.
The name for an entity is entered and displayed in the Name column. (Entity
names must begin with a letter and may contain numbers, underscores, dashes,
and full stops -- typically periods).
Documents using this schema may now include the content defined in the general
entity area using entity references, which look like:
&entityName;
The parser strips out the entity references and replaces them with the value of the
entity. For example, using the entities described in the figure above,
Our new & p r o d u c t N a m e ; (& p r o d u c t N u m ; ) is the finest of its breed.
will become:
Our new Capital 8850 (CXY-8850) is the finest of its breed.
entity, all markup within the referenced file must be well-formed. Optionally, a
public identifier (used in some SGML environments) may be provided. The
notation column should be left blank for an external general entity. Figure 33
illustrates the creation of an external general entity.
External general entities are referenced from documents the same way that
internal general entities are referenced -- using the & e n t i t y N a m e ; syntax. In this
case, & p l a y ; would reference the XML document 'othello.xml' and include it in a
document.
In the System column, you can use the Insert File Name button to browse for and
select a file in your project containing the desired content.
Notations
Notations allow you to describe a new data type or file type. The description
involves a name for the type and a link to more information on the type or to
programs that can process the type. For example, the notations declared in
Figure 35 provide information on ISO8601 dates and times, and Java integers.
Either could be used for a data type and will appear as an option in the type
menus that appear in the elements panel and attributes panel.
Figure 35 Notations
Each notation is listed in a row of the panel. Information associated with each
notation appears in columns across the panel and includes the following (from
left to right).
Column Description
Row Selector/Error This column allows you to modify the row and detect
Indicator errors in the declaration. See Common Columns In
Tables on page 26 for more information about this
column.
Column Description
Location Enter the URL that will serve as the system identifier
for the notation. System identifiers are not required
for notations, though at least one identifier (system or
public) must appear. System identifiers may point to
standards describing the content or to programs that
can actually process it.
Note: Use the Insert File Name button to browse for
and select a file in your project containing the desired
content.
Processing Instructions
Processing instructions are a relatively free-form way to include extra information
about your schema for an application to use.
Each processing instruction is listed in a row of the panel. Information associated
with each processing instruction appears in columns across the panel and
includes the following (from left to right).
Column Description
Row Selector/Error This column allows you to modify the row and detect
Indicator errors in the declaration. See Common Columns In
Tables on page 26 for more information about this
column.
Column Description
Target Enter the target name. The target needs to be a name
beginning with a letter and possibly containing
numbers, underscores, dashes, and periods.
Instruction Enter the instruction for the processor. The format for
the instruction is up to you, though it may not contain
the sequence ? > , which ends a processing instruction,
Errors Panel
When selected by way of the Schema > View menu or upon clicking the Errors
button on the toolbar, the errors panel appears between the active editing panel
and the configuration panel. The errors panel displays errors found when a new
DTD is loaded, as well as errors detected throughout the editing process.
The errors panel indicates the total number of errors and provides a list of errors
and details about the errors in this panel. Clicking on the error message will take
you to the source of the error.
To update error information in the DTD after correcting an error, it's good practice
to check for errors again by way of the Check for Errors button on the top of the
panel.
Notes Panel
The raw declarations in your schemas are very useful for parsers processing your
document, but are rarely sufficient for other humans who need to read and make
sense of your schema. Adding notes helps those who use and maintain your
schema to understand your schema designs, and can be a critical tool for keeping
groups of developers working on the same or related schemas in sync.
The notes panel provides an area where you can add schema level documentation
to your schema as well as document individual declarations and preview their
source. When selected by way of the Schema > View menu, the notes panel
appears between the active editing panel and the configuration panel.
Use the button in the upper right-hand corner of the notes panel to indicate
whether you are interested in working with declaration-level notes (the default
view) or notes about the schema as a whole. To view or edit notes for the schema
as a whole, click Show Document. (The name of the DTD will appear in the upper
left-hand corner of the panel.) To toggle back to the default, declaration-level
view, click 'Show Selected Declaration'. (The the name of the declaration will
appear in the upper left-hand corner of the panel.)
When the notes panel reflects the selected declaration, three tabs are available:
Tab Description
All Notes Displays all the notes entered for the selected declaration.
Notes cannot be edited within this tab.
Usage Notes Use this tab to associate a new note with the selected
declaration. In the source code, the note will appear within
the selected declaration, as an XML comment:
<!--usage note-->
Source Preview Displays the source code for the selected declaration.
When the notes panel reflects the document as a whole, two tabs are available:
Tab Description
All Notes Displays all the top-level notes. Notes cannot be edited
within this tab.
Usage Notes Use this tab to associate a new note with the schema. In the
source code, the note will appear as an XML comment
above the first declaration.
Source Panel
When selected by way of the Schema > View menu or upon clicking the Source
button on the toolbar, the source panel becomes the primary panel for editing.
The source panel allows you to edit the source code of your DTD directly. If you're
comfortable with DTD syntax, editing your declarations directly may
occasionally be useful or even convenient. Even if you don't want to edit your
DTD directly, the source panel provides another way to examine your
declarations.
To make the other panels reflect the changes you've made, click Reparse at the top
of the panel. Any errors found upon reparse will be listed in the errors panel.
DTD Exercise
To help you become familiar with the panels available when working with DTD
resources, we have included this step-by-step exercise. The exercise walks you
through the creation of a simple schema, introducing you to the fundamental
features of the editing environment. The exercise should take about 10-15 minutes
to complete.
In this example, you will build a DTD for a price list. A document conforming to
this schema could be used by a reseller to define the format in which product
information is received from manufacturers. Here is a guide to the information
we'll be using:
Component Description
price.list the “root” element inside of which all others will appear
Getting Started
1. In the project panel, create a project folder named QuickTour.
2. To create a new DTD resource, drag the DTD icon from the XML Tools palette
and drop into the design panel.
You can navigate around the tables in each panel by using ENTER, TAB,
SHIFT-ENTER, and SHIFT-TAB.
7. To create the next element, move your cursor to the row below m a n u f a c t u r e r
and type d a t e . i s s u e d . Tab to the Content column and select “Text” by
clicking on the Content Type button and selecting “Text” from the drop down
menu.
Now, go back and specify a content model for m a n u f a c t u r e r to ensure that the
manufacturer element always includes the d a t e . i s s u e d element.
8. Move to the Content column on the m a n u f a c t u r e r row and select “Elements”
from the Content Type menu. This restricts the content model for
m a n u f a c t u r e r to elements only.
9. Tab to the Content Model column and position the cursor inside the
parentheses “()” which are automatically created when editing an element's
content model.
10. Type d a t e . i s s u e d into the Content Model column to restrict the contents of
m a n u f a c t u r e r to one and only one d a t e . i s s u e d element. Since n a m e is an
attribute, it does not need to be within the m a n u f a c t u r e r element.
11. Move to the empty line below d a t e . i s s u e d and type p r o d u c t then press tab.
Select “Elements” from the Content Type menu and press tab.
12. Move to the content model column for p r o d u c t , position your cursor inside
the “()” and type s k u , p r o d u c t . n a m e , p r i c e , d e s c r i p t i o n , p r o m o t i o n
The commas between elements are indicative of a Sequence (this followed by this
followed by this). Elements may also represent a Choice (this or this or this).
Choice uses a “|” rather than a “,” between element names. In the Content Model
column, groups of elements can be EITHER choices or sequence. For more
information, see Building Content Models: Occurrence and Sequence Indicators
on page 87.
When adding elements to a content model (within the “Content Model” column),
if your input exceeds the column width, type Ctrl+E or select “Expand” from the
Schema>View menu to open a larger window for editing the selected area.
13. Tab from this field and select “Create” (fig 1.4) when prompted. Notice that
new Elements are created for you and added to the list. By default, new
elements are automatically created with text only content
.
Elements can be defined as either required OR optional. They may also be defined
as repeatable by clicking on the Repeatable button in the Content Model toolbar.
For more information, see Building Content Models: Occurrence and Sequence
Indicators on page 87.
15. A promotion is a discounted price over some period of time. This will be
represented using a combination of elements and attributes. Make a content
model for p r o m o t i o n by specifying “Elements” in the Content column and
then entering p r i c e into the Content Model column.
16. Tab to the Attributes column for p r o m o t i o n and enter start.date,
e n d . d a t e . Press Tab.
17. XML schemas typically have a single root element that contains all other
elements. In this instance, our root element will be called p r i c e . l i s t . Below
p r o m o t i o n , type in p r i c e . l i s t , press tab, and specify “Elements” content.
The Apply button makes the file available to other resources in the project. The
schema is saved when the entire project has been saved.
Graphical view
By defining content models, a structure for the document is established. This
structure can be thought of as a tree where the root is the encompassing element
and its branches are the elements and attributes that may be contained within it
(as defined by the content model). In turn each branch may have branches
defined by their content model. The diagram at the top of the element panel
provides a graphical view of these relationships. Explore the content model by
clicking on the elements to expand and collapse their content. (Specifically, click
on the Element Content Indicator icon, labeled in Figure 36 on page 117.) Note
that only elements that define a content model can be expanded. Within the
diagram, double clicking on the root element, in this case p r i c e . l i s t , will
produce a graphical view of the entire schema, shown in Figure 36.
For each element and attribute in the diagram, a right button menu offering key
editing functions is provided. Right-click the background to zoom in or out of the
diagram as a whole.
Source view
To view the actual schema syntax for the schema you've created, open the source
panel by clicking Source on the main toolbar. The notes panel, which allows you
to enter supplemental information about any element or attribute, also allows you
to view the source for individual declarations. Open the notes panel using the
Schema menu (Schema > View > Notes). Click on the “Source Preview” tab at the
bottom of the notes panel to view the source for the element declaration currently
selected in the element list.
Conclusion
Congratulations! You have completed the DTD Quick Tour. Notice that the
elements and attributes were not constrained by data typing beyond text, because
types such as i n t e g e r, d e c i m a l and d a t e are not available in a DTD. To see how
these types could be implemented in a price list schema, see XML Schema
Exercises on page 70
Instance
Resource
The Instance resource of the XML Tool palette enables the creation of an XML
instance document. XML instance documents are XML documents -- typically
representing data-oriented business documents, messages, and configuration files
-- that conform to the rules of an XML Schema or DTD.
When an Instance resource is selected within your project, a series of new panels,
toolbar buttons, and menus options are provided to facilitate the schema-driven
creation, editing, and navigation of the resource. The editing environment for
instance resources, shown in Figure 37 is described in this chapter.
For a hands-on demonstration of the instance editing environment, see the XML
Instance Exercise on page 137.
Configuration Panel
When editing an Instance resource, the Configuration tab has the following
fields:.
Field Description
Name This is the name of the file when persisted. The * . x m l suffix
will be automatically added.
Toolbar
For a description of the buttons that appear on the toolbar when editing Instance
resources, see Toolbar Buttons on page 27.
XML Menu
An XML menu becomes available when editing an Instance resource. The XML
menu contains three submenus: Tools, View, and Presentation.
The Tools menu includes options for inserting elements or attributes and for
locating and replacing text. The View menu provides options to control the panels
used for editing, organizing, and viewing your documents. The Presentation
menu allows you to associate one or more customized views with the active
instance document. The presentations are associated at the schema level, so the
views you create for a single document adhering to a schema become available for
all instances of the schema.
The XML menu options are described in detail in Menu Options on page 28.
Setting a Schema
The XML instance editing environment is optimized for building XML
documents based on an XML Schema or DTD. When creating a new XML
document, specifying the schema within your project to base the document on is
typically your first step. To set a schema, use the Set Schema button on the toolbar.
A window will appear enabling you to choose a schema from your project. Upon
selecting your schema, you will be prompted to specify a root element for your
document. A default value will appear, representing a “best guess” as to the root
of the schema you have selected. If the default value is correct, simply select OK
and the schema will be loaded. If the default value is not correct, type in the name
of the root you would like to use. If you decide that you do not want to set the
schema, click Cancel.
If you set a schema to a brand new document, the schema will be used to
“jumpstart” your document, automatically adding all required attributes and
elements into the content panel. Keep in mind, however, that your document will
likely not be error free until you have entered appropriate values in the edit area.
Use the Errors button on the toolbar to view a listing of validation errors in the
errors panel.
You can set a schema to an existing Instance resources as well. Any errors
detected will be immediately listed in the errors panel.
Right-click the Set Schema button to choose from a list of recently applied
schemas.
Content Panel
The content panel provides the primary editing area and loads by default when
an Instance resource is selected in the project panel. The content panel consists of
a left-hand listing of the elements and attributes (tag area) and a right-hand area
for inserting values for the elements and attributes (edit area). The content panel
also has a navigator bar for navigating throughout the document and a factory
bar for adding new elements, attributes, processing instructions, comments, and
text. The content panel is shown in Figure 38.
Edit
Tag
Area
Area
Content
Hints
Factory
Bar
Icon Component
Element
Attribute
Comment
Processing Instruction
Text
Along with the edit area, the tag area is where most of your work will be done
when building XML documents. For more information on the key tasks
performed within the Tag area, see:
• Inserting new elements, attributes, processing instructions, and comments on
page 122
• Modifying Document Structure on page 124
• Identifying Data-Entry Constraints on page 125
• Navigating the Document on page 125
• Creating a Customized View of the Tag Area on page 126
Insert box
Within the tag area, double click an element to generate a drop down box. This
box will always contain an empty box with a series of icons below which, when
selected, determine the type (element, attribute, and so on) and location (child,
sibling, parent) of the node to be entered. (The insertion default is an element
sibling.) If the document is based on a schema, any elements and attributes
available based on the schema's content models will also be appear in the insert
box, and can be added with single mouse click. Note in Figure 39 that the
elements appearing the drop down box are marked by various indentions which
represent their relationship to the selected element. In this case, s t r e e t and c i t y
are siblings to the selected element, s t r e e t , and hence, appear along the same
vertical line. The elements s h i p T o and i t e m appear to the left of the selected item,
indicating parent and grand-parent relationships, respectively.
insert schema-defined
element or attribute
If you are using a schema to build your document, adding new elements and
attributes may cause your document to become invalid. You will be permitted to
create documents that break from the structure of your schema, but will be alerted
whenever this occurs by way of the errors panel.
Factory Bar
The factory bar at the bottom of the content panel, provides another option for
entering new items to the tag area. The factory bar is shown in Figure 40.
The factory bar provides an easy way to identify and insert any additional
elements (children or siblings) or attributes defined by the schema for the element
selected in the tag area. Click on any element of attribute name appearing on the
factory bar to have it automatically added to the document.
The factory bar also facilitates the insertion of new elements and attributes, as
well as new comments, processing instructions, and text. Click the blue icon
representative of the item you would like to add to launch the Insert box
described above. Figure 41 illustrates the insert box which appears after clicking
on the comment icon on the factory bar.
You can also use your mouse to quickly change the positioning of elements and
attributes appearing in the tag area. This “drag and drop” editing can be used to
change the structure of your document or simply to change the view of your
document. (For more information, see Promoting elements and attributes on
page 130). To move an element or attribute, left click on the blue icon which
appears to the left of the tag. Holding down the left mouse button, drag the item
to its new position and release the mouse button. If your document is dependent
on a schema, be sure to use the Errors button on the toolbar to determine if the
move is permitted by the schema.
Clicking on an element in the navigator bar will also open a drop down window
displaying the selected element and each of its siblings. Figure 45 shows the
siblings for the b i l l T o element.
By presenting elements in the context of their parents and siblings, the navigator
bar provides a clean view of an element’s place in the document's structure, a
feature which is particularly useful when your documents are lengthy. The
navigator bar also facilitates navigation throughout your document. Double
clicking on an element from the drop-down automatically moves you to that
element within the tag area.
Customization is performed using the right button menus associated with each
tag. The initial menu that appears is used to customize tags on an individual item
basis. That is, if the document uses several a d d r e s s elements, the menu choice
will only affect the a d d r e s s element that is selected. The final option of this menu
provides access to a type level sub-menu. The options within this menu affect all
instances of a given element within your document. Both the item and type level
menus are shown in Figure 46.
To learn more about the customization options on the right-button menu, see:
• Expanding and collapsing elements on page 128
• Hiding elements and attributes on page 128
• Creating aliases for elements and attributes on page 129
• Adding color to your tags on page 129
• Promoting elements and attributes on page 130
Type level changes made through the application of each of these options can be
saved by way of the XML menu (XML> Presentation > Save As...)
The alignment of the tags can also be changed by way of the XML menu
(XML>View>Align Labels).
To show all elements and attributes previously hidden, select the Show All option
of the right button menu for the root element of the document.
Once a color has been selected, the tag’s default background color (light gray) will
change to the chosen color.
If you want to promote a large number of child elements, you can resize an
element row to allow for multiple lines of promotion per element. To resize an
element row vertically, click on the bottom of the row in the area just to the left of
the split bar separating the Tag and Edit Areas and then drag to the desired size.
An element row can be re-sized to allow for a maximum of 7 lines per row. In
Figure 51, the row for the element m o n t h l y has been resized to allow for three
lines of promotion.
To cancel a promotion, right click the promoted item and choose Demote from the
menu.
Promoting elements and attributes does not change their structural position
within the XML document, just their position within the content panel.
Content Hints
If your document is based on a schema, content hints facilitate valid data entry by
providing information about the schema's content model. The hints appear as
grayed-out text strings in the edit area next to each structural element. Figure 52
illustrates the different types of content hints.
Content hints in parentheses represent the sequence and occurrence of any data
elements contained by the particular structural element. The content models are
described using occurrence and sequence indicators. Table 13 describes the
Occurrence indicators. Table 14 describes the Sequence indicators.
Occurrence
Meaning
Indicator
None The element must appear once and only once.
Occurrence
Meaning
Indicator
| Can be read as 'or'. Creates content model with particles
enumerated (only one may be chosen).
& Elements may appear in any order, but may not be repeatable.
Besides element content, content hints also provide data typing and default value
information. Also, if the schema enumerates values for an element or attribute, a
drop down list of the possible choices is provided (when you click on the data
entry field.)
For a description of the data types that may appear as content hints, see
http://www.w3.org/TR/xmlschema-2/#built-in-datatypes
Content hints are displayed by default. They can be turned off by way of the XML
menu (XML > View > Content Hints).
Errors Panel
When you set an XML document to a schema, an initial validation check is
performed to ensure that your document is in agreement with the rules outlined
by the schema. As you make changes to your document, use the Check for Errors
button on the top of the panel to determine if the changes are valid. Detected
errors are displayed in the errors panel, located below the Content or Source
panel.
The errors panel contains a listing of errors along with a brief description. Typical
error messages indicate:
• data that does not match the data type specified by the schema
• elements in the improper sequence
• elements or attributes not defined in the schema
Click on the error within the errors panel to identify where the error exists within
the document. The problem area will be highlighted within the Tag and Edit
areas.
If the document does not reference a schema, upon checking for errors the errors
panel will indicate one error:
Element “root”: Document has no governing schema
This message is not indicative of an error; rather, it indicates that the instance
cannot be checked for validity errors as it is not governed by a schema.
Source Panel
When selected by way of the XML > View menu or upon clicking the Source
button on the toolbar, the source panel becomes the primary panel for editing.
The source panel allows you to edit the source code directly. If you're comfortable
with XML syntax, editing directly within the XML source may be useful.
To make the other panels reflect the changes you've made, click on 'Reparse' at the
top of the panel. Any errors found upon reparse will be reported.
UTF-8 is set as the default encoding for XML resources. The encoding can be
changed on the XML Editing tab of the Preferences window (Edit>Preferences).
To help you become familiar with the editing facilities available when working
with Instance resources, we have included this step-by-step exercise. The exercise
walks you through the creation of an XML instance document, introducing you to
the fundamental features of the editing environment. This exercise should take
around 15 minutes to complete.
This exercise requires the use of the price list schema created in the first XML
Schema exercise.
Getting Started
1. In the project panel, create a project folder named QuickTour.
2. To create a new Instance resource, drag the schema icon from the XML Tools
palette and drop into the design panel.
3. Within the design panel, double click the schema icon.
4. A series of new panels will appear, displaying a new XML document with just
the root element showing. If you wanted to create a new document without
the use of a schema, you could simply rename (right-click > rename) the root
element to a tag name of your choice and then build your document from
there. In our example, however, we are going to create this document based
on the price list schema.
5. Click the Set Schema button from the toolbar at the top of the screen. A dialog
will appear enabling you to browse and open the pricelist schema you created
in the XML Schema exercise.
6. A dialog box will appear asking you to select an element to serve as the root
element. The element p r i c e . l i s t will appear as the default selection. Click
OK.
7. After setting the schema, you will notice the elements (indicated by a blue
diamond icon) declared as required in the schema now show up in the tag
Edit area
Tag area
Content hints
Factory bar
Upon setting the schema, two error messages will be reported in the errors panel.
These errors will be resolved later in this exercise.
insert schema-defined
element or attribute
2. Select p r o m o t i o n within the tag area, and use the factory bar to add the
s t a r t . d a t e and e n d . d a t e attributes.
S
3. Now you can promote the child elements as well as the attributes of
m a n u f a c t u r e r to make the entry of data easier and the document view more
manageable.
Promotion is especially helpful when working with data-centric documents
containing a lot of mark-up but little content. To do this, move your pointer
over the small blue icon next to the attribute name and drag the attribute to
the right into the edit area and move it up one row. There will be a small black
indicator that will demonstrate where the attribute is going to be repositioned.
Release the attribute next to its associated element m a n u f a c t u r e r.
4. Now drag the element d a t e . i s s u e d up to the right of the attribute n a m e , on
the same level of m a n u f a c t u r e r.
Promoting the elements does not change their structural position within the XML
document, just their position within the content panel.
7. To illustrate the entry of data, click to the right of the n a m e attribute and enter
a value that conforms to the data type, in this case a s t r i n g .
8. Continue to enter the appropriate data into the remaining fields, using either
the Tab key or the mouse to move between fields. When entering the content,
pay attention to the data type information as specified by the schema and
indicated by the content hints. Dates should be entered in the format:
YYYYMMDD.
Prices should be entered as decimal data. As you enter data corresponding to
the required data type, the errors reported in the errors panel will disappear.
9. To add another p r o d u c t to the price list, highlight p r o d u c t in the tag area and
then select p r o d u c t from the factory bar. Notice that the new p r o d u c t tag
retains the formatting already specified for its element.
Congratulations! You have completed the example for customizing and building
an XML document from a schema. One important feature is that once you create
a document based on a schema, each additional document you make that uses the
same schema will have the same view. To test this, save your document (using the
Apply button of the configuration panel) and then start a new document and set
the same pricelist schema to start it. Immediately upon setting the schema, the
view of the new document will be the same as this document. Use the
Presentation menu (XML > Presentation) to return to the default view or to save a
new view of the document.
This chapter gives detailed information about the Adapter Resources palette.
Topics
This section gives an overview of how you can use TIBCO Designer to specify an
adapter configuration. It discusses these topics:
• Configuring a New Adapter Instance
• Adding Services to Your Adapter
• Advanced Adapter Configuration
• Adding Custom Log Sinks to Your Adapter
• Adding Extended Properties to Your Adapter
• Adding Custom Hawk Microagents to Your Adapter
• A Note on Global Variables
• Using a Message Filter
• Testing Your Adapter Using Adapter Tester
Overview
The G e n e r i c A d a p t e r C o n f i g u r a t i o n resource and the associated A d a p t e r
R e s o u r c e s palette are used when developing an adapter using the TIBCO
Adapter SDK API. The adapter is configured using the Generic Adapter
Configuration resource and the configuration is saved to a project repository,
which is used by the code you have written.
This manual discusses all resources in the Adapter Resources palette. This chapter
explains how to use the resources, later chapters provide a reference to individual
resources and the settings you specify in the configuration panel.
1. Open TIBCO Designer. In the startup window, choose New empty project or
open the project to which you wish to add your adapter.
2. Save the project. See TIBCO Designer User’s Guide, available via Help >
Designer Help for information on saving projects.
3. In the project panel of the main window, make sure the top-level (project)
folder is selected.
4. From the palette panel, drag a G e n e r i c Adapter Configuration into the
design panel.
5. In the configuration panel, specify the configuration information for the
adapter. See Generic Adapter Configuration Reference on page 156.
The easiest way to configure a new adapter is to drag a service into the design
panel and configure it (and its metadata). If necessary, you can then perform
additional configuration on the endpoint created by TIBCO Designer.
Creating the session and endpoint explicitly is cumbersome and not
recommended.
3. In the configuration panel give the service a name and choose the transport
type.
5. If the schema that determines the data used by the service has already been
defined, click the S c h e m a tab, then click the browse icon (binoculars) and
select the schema resource in the dialog that appears.
You must be sure to assign the appropriate schema to the service. The default,
a n y, is only there as a placeholder.
6. Click Apply.
TIBCO Designer creates the service instance. If you need to perform
additional customizations, you can open the A d v a n c e d folder and do it there.
See Advanced Adapter Configuration on page 147.
1. Select the adapter, then choose the Logging tab and click the Advanced
Logging check box.
Terminology
Keep in mind the following terminology used to describe repository content.
• An object contains attributes.
Adding Properties
To add an extended property to your adapter, follow these steps:
Click this icon to add an association list. Because a named association list is
called an attribute, you have, in effect, added an attribute to an object when
you add an association list. Note that you can also add an association list to an
attribute. This adds an extended property to the attribute.
Click this icon to add a reference to an existing object. When you add a
reference, you must then specify the global name to which the reference points.
The global name specifies the location of the object inside TIBCO Repository,
for example
/tibco/public/endpoint/adapter/generic/Generic Adapter
Configuration/RV TX Publisher
Click this icon to add a string property to an association list. Triple-click the
newly-added property to change the property name and its value.
Deleting Items
You can delete an object, association list, or attribute by selecting it, then
clicking the delete icon.
The programming for the Message Filter is performed with the Adapter SDK and
discussed in the Adapter SDK Programmer’s Guide. This resource only allows you
to hook in the resource.
Usage Scenarios
• The adapter wants to transform all outbound XML with XSLT
The application to which the adapter connects understands XML natively. The
adapter code retrieves messages and makes use of the M D a t a : : t o X M L ( ) methods.
The corresponding XSD is available in-memory and on disk if you have exported
it. To achieve local transformations to a “canonical format”, XSLT is the logical
choice. These transformations can be applied to all outbound endpoints. Inbound
transformations most likely don’t make sense.
• Arbitrary custom data manipulation is desired (not XSLT)
Some custom code is required to manipulate messages before sending them to a
third-party application. For example, a legacy TIBCO Rendezvous application
expects its data in a particular format. The only solution today is to write an
intervening adapter between packaged adapters and the TIBCO Rendezvous
application to do TIBCO Rendezvous transformations, or to use other TIBCO
products (TIBCO IntegrationManager, TIBCO ActiveMatrix BusinessWorks).
Implementation
The low-level callout behavior is made available by an M T r a n s f o r m a t i o n P l u g i n
class that is part of the API (both C++ and Java). See the reference documentation
for TIBCO Adapter SDK for additional information.
You specify the low-level callout in TIBCO Designer as follows:
1. With the top level project selected, drag a M e s s a g e Filter resource into the
design panel. Name it appropriately for clarity.
2. Specify the name of the implementing class in the I m p l e m e n t a t i o n field.
b. Specify the name of the attribute and the value you wish to use for this
adapter instance.
c. Click Is Reference if the attribute is also another object.
4. Click Apply.
You associate the callout with your adapter as follows:
1. Select the G e n e r i c A d a p t e r Configuration resource and choose the
C o n f i g u r a t i o n tab.
2. Click the Browse button next to the M e s s a g e Filter field and select the
M e s s a g e F i l t e r you defined earlier.
You can now access the attributes set in your configuration from your adapter
code. Here is an example for accessing an attribute test with value t e s t s t r i n g .
In Java: myStringProp =
mapp.getConfigProperties().getString(app.getAppParameters().getApp
Name() + "/deployment/transformationPlugin/attributes/test");
The transformation plugins are applied only to services with subscriber, publisher,
client, and server endpoints.
You can use the transformation plugin to stop the message flow. You can either
throw an exception or return F A L S E to stop message flow.
It is highly recommended you validate the project before starting adapter tester.
All adapters you wish to test, must have their runtime installed in your machine.
Because the setup differs depending on the type of adapter you are testing, this
section explains how to use the tool in three sections:
• Setup for Testing TIBCO Adapters
• Setup for Testing Custom Adapters
• Using Adapter Tester
When you set up an adapter tester, configuration for the tester is saved for each
adapter in the project. You may, however, have to change some of the settings if
you wish to run the tester on a different machine as the directories may not be
valid.
Working Click Browse to supply the directory. The tester creates the
directory necessary run-time and support files required by the
adapter in this directory. All files created by the Adapter
Tester are temporary and will be deleted when you exit
TIBCO Designer.
It is recommended that you do not edit the files in the
working directory. Ensure that the disk where the working
directory is located contains enough space to save multiple
copies of your project.
Adapter Choose the adapter from the pop-up. Make sure that the
executable version of the run-time matches the version of the
configuration.
The adapter executable to run your 'packaged adapter' will
be shown from a list of choices (each matching a particular
installation). If the adapter supports multiple executables
(one for a publisher, the other for a subscriber) be sure to
select the correct one for the configuration you want to
test.
Adapter Tester may work with GAC and other custom type adapters,
however, TIBCO only supports this feature on packaged adapters.
TRA template TRA template to use for the adapter. The tester tool will
copy values in the template and perform any necessary
variable expansions as well as add additional entries
pointing to the project file, etc.
If the adapter specifies global variables, you can enter values in the window that
is displayed.
If your GAC or custom adapters cannot be successfully run by providing the
above values, you can check the C u s t o m S h e l l C o m m a n d check box.
This allows you to enter the working directory and shell command to execute.
The shell command should include all arguments necessary to run the adapter.
Note that in this mode, the project is not exported. You have to perform the export
yourself. You may also need to create your own TRA file.
See the TIBCO Adapter SDK Programmer’s Guide more information on the available
arguments and options for custom adapters.
Configuration Tab
The C o n f i g u r a t i o n tab allows you to specify the following information:
SDK AppName Short name of the adapter used in the source code.
Two buttons at the bottom of the Configuration tab allow you to change
configuration values.
Edit Adapter Allows you to edit the raw adapter xml configuration. You
XML should use the palette features to edit the adapter. You are
responsible for making sure the configuration is valid.
Logging Tab
The L o g g i n g tab allows you to specify your logging preferences and information.
You have two choices:
• If you are using custom roles, choose Advanced Logging, then use the
resources in the Log Sinks folder to configure logging information. See
Custom Log Sink Reference on page 170.
• If you are not using custom roles, use the check boxes in this tab. You can send
the information to multiple locations, and you can choose to log one or more
message types.
Use Advanced When this check box is selected, you configure log
Logging
sink resources from the Log Sinks folder of the
adapter’s Advanced folder. See Custom Log Sink
Reference on page 170.
Startup Tab
The S t a r t u p tab allows you to specify startup information for your adapter.
Monitoring Tab
The M o n i t o r i n g tab allows you to provide TIBCO Hawk information for the
standard TIBCO Hawk microagent. See Adding Custom Hawk Microagents to
Your Adapter on page 150 for information on configuring custom microagents.
Class MicroAgent Timeout Specifies the amount of time the Hawk Agent
should wait for HMA method invocations to
complete before timing them out. The default
is 10000 milliseconds. Normally there is no
need to change this value, however, on
machines under extreme stress where method
invocations are timing out, this new option
allows the timeout value to be increased.
Services Reference
Publication Service
When you choose a publication service, the configuration panel allows you to
specify information in the following:
• Configuration Tab
• Transport Tab (Rendezvous Transport)
• Transport Tab (JMS Transport)
• Schema Tab
Configuration Tab
Message Subject with which this publisher will send out messages.
Subject
Do not change the subject unless you understand TIBCO
Rendezvous requirements.
Wire Format If a JMS transport is used, the wire format is always XML
Message.
Connection Choose Q u e u e or T o p i c .
Factory Type
Schema Tab
Each service must be associated with schema that describe the data the service
sends or receives. Click the Browse icon to associate the schema that describe the
data the service actually sends or receives.
Subscription Service
When you choose a publication service, the configuration panel allows you to
specify information in three tabs (only one of the Transport Tabs will be available):
• Configuration Tab
• Transport Tab (TIBCO Rendezvous Transport)
• Transport Tab (JMS Transport)
• Schema Tab
Configuration Tab
Connection Choose Q u e u e or T o p i c .
Factory Type
Schema Tab
Each service must be associated with schema that describe the data the service
sends or receives. Click the B r o w s e icon to associate the schema that describe the
data the service actually sends or receives.
• Configuration Tab
• Transport Tab (TIBCO Rendezvous Transport)
• Transport Tab (JMS Transport)
• Schema Tab
Configuration Tab
Message Subject with which this publisher will send out messages.
Subject
Do not change the subject unless you understand TIBCO
Rendezvous.
Connection Choose Q u e u e or T o p i c .
Factory Type
Schema Tab
Each service must be associated with schema that describe the data the service
sends or receives. Click the B r o w s e icon to associate the schema that describe the
data the service actually sends or receives.
Request-Response Service
An ActiveEnterprise request-response service takes on the role of the server in an
ActiveEnterprise operation. Provide the information for the following tabs to
configure the service:
• Configuration Tab
• Transport Tab (TIBCO Rendezvous Transport)
• Transport Tab (JMS Transport)
• Schema Tab
Configuration Tab
Connection Choose Q u e u e or T o p i c .
Factory Type
Schema Tab
Each service must be associated with schema that describe the data the service
sends or receives. Click the Browse icon to associate the schema that describe the
data the service actually sends or receives.
The Log Sinks folder allows you to configure advanced logging behavior.
For basic logging behavior, use the Logging tab of the adapter instance. See
Logging Tab on page 156.
File Sink
For a file sink, you specify the following information:
File Name Global variable that includes the path and name of trace
file. Extension . l o g is suggested.
Append Mode If checked, traces are added to the existing file at startup. If
unchecked, the existing file is overwritten at startup if one
of the same name exists. Only true and false are legal
values.
The default file sink that is part of each adapter has those roles predefined that
were selected when you turned on A d v a n c e d L o g g i n g . If you create additional
file sinks, you can add roles. See Adding Roles to Sinks on page 173
3. When F i l e L i m i t has been reached (that is, as soon as the file is as big as or
bigger than the limit) the adapter renames the current file to file.1 and creates a
new file with no extension.
4. Note that the log file can be slightly larger than the limit because the new file
is only created after the limit has been reached.
5. The adapter repeats this process until it reaches the number of files specified
in F i l e C o u n t .
The adapter overwrites the file with the highest number, that is, the oldest file,
when the number of files reaches F i l e C o u n t and that last file reaches F i l e
L i m i t . To avoid that, set either F i l e C o u n t or F i l e L i m i t to a sufficiently large
value.
stdio Sink
For a stdio Sink, you specify the following information.
Network Sink
To add a network sink:
Session Click the B r o w s e icon and select one of the sessions you
defined.
Hawk Sink
A Hawk sink sends messages to TIBCO Hawk. To add a Hawk sink:
MicroAgent Name of the microagent for traces from this Hawk sink.
Name
Sessions Reference
When you add a service to an adapter, TIBCO Designer automatically creates the
corresponding session and endpoint, depending on the protocol and delivery
mode being used. Session and endpoint are placed in the A d v a n c e d folder of the
G e n e r i c A d a p t e r C o n f i g u r a t i o n . This section is a reference to the sessions
included with TIBCO Designer.
To Create a Session
1. Select the A d a p t e r Services folder in the project panel.
2. Drag a service (e.g. a P u b l i c a t i o n Service) into the design panel.
3. Specify the transport type and fill in the information in the T r a n s p o r t tab.
4. TIBCO Designer creates the service and creates a corresponding session and
endpoint in the A d v a n c e d folder.
RV Session
For TIBCO Rendezvous sessions, the configuration panel includes the following
information.
To edit the global variables used in this panel, click the G l o b a l V a r i a b l e s tab in
the project panel in the upper left quadrant. For more information, see TIBCO
Designer User’s Guide.
Service Global variable that specifies the service for this session.
By default, the variable is defined to be the default TIBCO
Rendezvous service (7500).
Network Global variable that specifies the network for this session.
By default, the variable is an empty string, which is
interpreted as the primary network. Using this attribute
only makes sense on computers with more than one
network interface.
SSL Check this option if you wish to use SSL. See Chapter 5,
Managing Trusted Certificates, on page 107 in TIBCO
Designer User’s Guide.
RVA Session
For RVA sessions, the configuration panel includes the following information.
To edit the global variables in this panel, click the G l o b a l V a r i a b l e s tab in the
project panel in the upper left quadrant. For more information, see TIBCO
Designer User’s Guide.
Port Global variable that specifies the port number for this
session. This attribute is ignored if the host is not
specified.
Enable HTTP When checked, first try to connect to rva through the
specified port; if that attempt fails, then try tunneling
through the HTTP port.
When unchecked (the default), do not try HTTP
tunneling.
RVCM Session
For RVCM sessions, the configuration panel includes the following information.
To edit the global variables, click the G l o b a l V a r i a b l e s tab in the project panel
in the upper left quadrant. For more information, see TIBCO Designer User’s
Guide.
Service Global variable that specifies the service for this session.
By default, the variable is defined to be the default TIBCO
Rendezvous service (7500).
Network Global variable that specifies the network for this session.
By default, the variable defaults to the empty string, which
is interpreted as the primary network. Using this attribute
only makes sense on computers with more than one
network interface.
SSL Check this option if you want to use SSL. See Chapter 5,
Managing Trusted Certificates, on page 107 in TIBCO
Designer User’s Guide.
RVCMQ Session
For RVCMQ sessions, the configuration panel includes the following information.
To edit the global variables in this panel, click the G l o b a l V a r i a b l e s tab in the
project panel in the upper left quadrant. For more information, see TIBCO
Designer User’s Guide.
Service Global variable that specifies the service for this session.
By default, the variable is defined to be the default TIBCO
Rendezvous service (7500).
Network Global variable that specifies the network for this session.
By default, the variable defaults to the empty string, which
is interpreted as the primary network. Using this attribute
only makes sense on computers with more than one
network interface.
SSL Check this option if you want to use SSL. See Chapter 5,
Managing Trusted Certificates, on page 107 in TIBCO
Designer User’s Guide.
CMQ Name Sequence of global variables that specifies the name of the
queue.
Complete Time If the complete time is non-zero, the scheduler waits for a
(ms)
listener member to complete an assigned task. If the
complete time elapses before the scheduler receives
completion from the listener member, the scheduler
reassigns the task to another listener member. Default is 0.
See TIBCO Rendezvous Concepts for more information.
Scheduler When the heartbeat signal from the scheduler has been
Activation
silent for this interval (in milliseconds), the queue member
(ms)
with the greatest scheduler weight takes its place as the
new scheduler.
All member sessions in the queue must specify the same
value for this parameter. Acceptable values are unsigned
32-bit integers (except zero). Defaults is 3000.
RVTX Session
For TIBCO Rendezvous TX sessions, the configuration panel includes the
following information.
To edit the global variables in this panel, click the G l o b a l V a r i a b l e s tab in the
project panel in the upper left quadrant. For more information, see TIBCO
Designer User’s Guide.
Service Global variable that specifies the service for this session.
By default, the variable is defined to be the default TIBCO
Rendezvous service (7500).
Network Global variable that specifies the network for this session.
By default, the variable defaults to the empty string, which
is interpreted as the primary network. Using this attribute
only makes sense on computers with more than one
network interface.
SSL Check this option if you want to use SSL. See Chapter 5,
Managing Trusted Certificates, on page 107 in TIBCO
Designer User’s Guide.
JMS Session
For JMS sessions, the configuration panel includes the following information.
To edit the global variables in this panel, click the G l o b a l V a r i a b l e s tab in the
project panel in the upper left quadrant. For more information, see TIBCO
Designer User’s Guide.
(JNDI) Connection Username for logging into the JMS server or JNDI
Username
server.
(JNDI) Connection Password for logging into the JMS server or JNDI
Password
server.
Basic Tab
For the Basic tab, either click Copy From to use the SSL information used by
another session, or fill in the following fields.
Trusted Certificates Click the browse icon and select the folder in which
Folder the trusted certificates to be used by this transport are
stored. See Chapter 5, Managing Trusted Certificates,
on page 107 in TIBCO Designer User’s Guide.
Advanced Tab
If you wish, you can also provide the following advanced information:
i
Verify Host This field specifies that the host name of the HTTP server
Name
should be checked against the host name listed in the
server’s digital certificate. This provides additional
verification that the host name you believe you are
connecting to is in fact the desired host.
If the specified host name is not an exact match to the host
name specified in the server’s digital certificate, the
connection is refused.
Note: If you specify an equivalent hostname (for example,
an IP address), but the name is not an exact match of the
hostname in the host’s digital certificate, the connection is
refused.
Expected Host This name must match the name in the certificate.
Name
Strong Cipher If checked, only strong Cypher Suites are allowed. See
Suites Only
OpenSSL v3.0 Cipher Suite List on page 182 for a list of
available suites.
SSL_RSA_WITH_NULL_SHA NULL-SHA C
SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA C
SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA C
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 C
SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 C
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA C
SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA C
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA C
When you select the A d v i s o r i e s folder, you can specify advisory resources and
associate each advisory with a session.
This chapter provides reference information for the Transaction Controls and the
Advisories folders.
Transaction Controls
Adapters use transaction control pools in conjunction with RVTX. To specify a
transaction control pool, follow these steps:
Driver Class Name Name of the class that represents the JDBC driver
JDBC URL Connection URL that tells JDBC how to create a driver
and connect with it to the database.
Maximum Controls Upper bound for the number of transaction controls that
can be created.
Maximum Controls Upper bound for the number of transaction controls that
can be created.
Maximum Controls Upper bound for the number of transaction controls that
can be created.
XA Control Pool
For an X A control pool, you can specify the following information
Advisories
You can create one or more advisories and associate it with a session in your
application. Follow these steps:
Folder Reference
This section is a reference to the folders used by TIBCO Designer. The section is
mostly meant for online help access. It discusses folders used by the G e n e r i c
Adapter Configuration.
Overview
By default, TIBCO Designer provides a number of folders as a part of every
adapter configuration. These folders provide easy, organized access to every
configurable adapter feature.
Figure 58 shows the layout of the default folders.
Advanced Folder
The A d v a n c e d folder is part of every adapter configuration. It contains resources
that are created by TIBCO Designer while the adapter developer configures the
adapter. The folder can include sessions, endpoints, advanced logging and so on.
The configuration of these resources can be changed for situations that require
custom settings.
In most situations, adapter developers configure the resources in the A d a p t e r
Services folder. They may then access the resources in this folder for certain
custom configuration.
Sessions Folder
The S e s s i o n s folder stores sessions and endpoints associated with an adapter’s
services.
When you specify services for an adapter, TIBCO Designer creates the
corresponding sessions and endpoints. You can then edit the sessions and
endpoints in this S e s s i o n s folder if customization not available for the service is
required. See , Sessions Reference and , Custom Log Sink Reference.
Timers Folder
The T i m e r s folder stores timers for an adapter.
If you configure an adapter for which a palette is predefined, and timers are
available for this adapter, they are included in this folder.
If you configure a custom adapter, you create timers explicitly. See Timer on
page 199.
Advisories Folder
The A d v i s o r i e s folder stores advisories for an adapter.
If you configure an adapter for which a palette is predefined, and advisories are
available for this adapter, they are usually one of the services you work with.
If you configure a custom adapter, you create timers explicitly. See Advisories on
page 186.
You specify the locations where the adapter will look for additional metadata (the
metadata search URL) directly in the S t a r t u p tab for the adapter configuration.
If you define custom schema for your adapter, you should create a folder inside
the appropriate Schemas folder for those custom schema, then specify the path in
this L o a d U R L . To do so, click Browse to choose the location. See the Chapter 4,
Adapter Schema Palette, for more information.
Endpoint Reference
In most cases, you do not create endpoints explicitly. Instead, TIBCO Designer
creates a session and an endpoint for you when you create a service.
This section also discusses timers, which can potentially be used to trigger actions
just like endpoints. The following topics are covered:
• Endpoints Overview
• Publisher Endpoints
• Subscriber Endpoints
• Client / Request-Response Invocation Service Endpoints
• Server / Request-Response Service Endpoints
• Timer
• Adding Schema to Endpoints
Endpoints Overview
When you create a service by dragging a resource from the Adapter Services
folder into the design panel, TIBCO Designer creates the corresponding session
and endpoint in the Advanced folder of the G e n e r i c A d a p t e r C o n f i g u r a t i o n
you are using. If you cannot fully configure the endpoint from the Adapter
Services folder, you can access it in the Advanced folder and make changes there.
This chapter lists the available fields for each endpoint.
Publisher Endpoints
A publisher sends data to TIBCO Rendezvous or TIBCO Enterprise Message
Service. A publisher is associated with a schema class that specifies the data to be
published. Also associated with a publisher is a session. Sessions of several types
are supported. The session for a publisher determines the wire format it can use.
For JMS sessions, you can also change the delivery mode.
Endpoint Type Choose from the pop-up, which displays the allowed types
for the current session.
Subject Subject with which this publisher will send out messages.
RVCM Publisher
For an RVCM publisher, you supply the following information:
Endpoint Type Choose from the pop-up, which displays the allowed types
for the current session.
Subject Subject with which this publisher will send out messages.
Message Time after which the message is discarded from the ledger
Timeout (ms)
file. Default is 0 seconds, meaning that the timeout is
infinite.
RVTX Publisher
For a TIBCO Rendezvous TX publisher, you can supply the following
information:
Endpoint Type Choose from the pop-up, which displays the allowed types
for the current session.
Subject Subject with which this publisher will send out messages.
Subscriber Endpoints
Subscribers specify the data consumers in the applications.
When you create a subscriber, the choices you get depend on the session in which
the subscriber is created.
Endpoint Type Choose from the pop-up, which displays the allowed types
for the current session.
Subject Subject with which this publisher will send out messages.
JMS Subscribers
You supply the following information for subscribers using JMS as a transport:
See "The SDK Operation Model" in TIBCO Adapter SDK Programmer’s Guide for
more information.
Creating sessions explicitly and adding clients to the session is not recommended.
Instead, you should create the service you need, and let TIBCO Designer create
the session and endpoint. If there are changes you cannot make directly to the
service, you can then make them to the corresponding session or endpoint.
Endpoint Type Choice of endpoint types for the session to which the client
currently belongs.
Endpoint Type Choice of endpoint types for the session to which the client
currently belongs.
See "The SDK Operation Model" in TIBCO Adapter SDK Concepts for more
information.
Endpoint Type Choice of endpoint types for the session to which the client
currently belongs.
Endpoint Type Choice of endpoint types for the session to which the client
currently belongs.
Timer
TIBCO Designer allows you to add a timer to your adapter configuration. The
timer can then be used by the adapter program.
To add a timer, follow these steps:
This chapter discusses the Adapter Schema palette. You can use this palette for
configuring custom schema for custom adapters that were implemented using the
TIBCO Adapter SDK.
Topics
You can then use the Generic Adapter Configuration with the associated Adapter
Resources palette to configure the adapter. You configure the schema for the
adapter using the AESchemas folder and associated Adapter Schemas palette, as
discussed in this chapter.
Schema Basics
The TIBCO schema resources form the basis for model-driven computing with
your adapter. Applications use schema to describe the data a particular subscriber
or publisher receives from or publishes to TIBCO Messaging. That means that the
schema data describe the data inside the TIBCO messages the adapter deals with.
To use any of these resources, you should always first drag an A E S c h e m a resource
into the Design panel, then add your own resources to the folders that are created.
To use any of these resources, you should first create a separate folder and add
resources to it as needed.
The exact process differs for each adapter and is discussed in the adapter’s
documentation.
1. With the project displayed in the Design panel, drag a PeopleSoft Adapter
Configuration resource from the palette panel into the design panel.
2. Find the adapter instance in the project tree, and open its Adapter Services
folder.
A number of services become available in the palette panel.
3. Drag a Subscribe Event into the design panel.
In the configuration panel, the configuration tab changes to allow you to
specify configuration information.
4. Click Fetch Component Interface Name.
TIBCO Designer displays a window in which you can select the component
interface to which you want to subscribe.
5. Choose Product, click OK, then click Apply in the configuration panel.
You can now save your project with the new adapter including the subscriber and
the schema for the subscriber.
• Under the Schema tab, displays the schema in that interface. Click on the
folders to see the fields and field types (which will translate to attributes and
attribute types).
• Creates a session of the appropriate type in the Advanced Settings/Sessions
folder.
• Creates a folder in the Schema/classes/ae folder for the application and adds
class resources matching the schema with attributes matching the fields.
• Under the Advanced tab, displays the message subject, endpoint reference,
and schema class reference.
— The endpoint reference points to the session that was created.
— The schema class reference points to the class created for this component
interface.
Defining Schema—Overview
This section gives an overview of the schema definition steps, pointing to other
sections as appropriate.
To define schema for your adapter, follow these steps:
1. In the project tree panel, select the A E S c h e m a s folder and double-click the ae
folder.
2. From the palette panel, select a F o l d e r resource (G e n e r a l palette) and drag it
into the design panel.
3. Name the folder appropriately for your adapter.
5. Select the Classes folder. From the palette panel, drag a Generic class into the
design panel and choose a class type. Then proceed to configure the class as
discussed in Defining a Class with Attributes on page 209 and Defining a
Class with Operations on page 212.
When you are configuring a service, you can then add the schema to the service
by clicking the Browse icon in the S c h e m a s tab.
To add the schema object to an endpoint (for example, a publisher) explicitly,
follow these steps:
1. In the project panel, select the endpoint while the schema object is visible.
2. From the project panel, drag the schema object into the design panel with the
endpoint still selected.
TIBCO Designer creates a reference to the schema object and includes it below
the endpoint in the hierarchy.
AESchemas Folder
When you launch TIBCO Designer, the project tree always includes an A E S c h e m a s
folder immediately under the top-level folder.
The A E S c h e m a s folder is the repository for all schema data used by all
applications in your project.
• When you configure a standard adapter, TIBCO Designer creates schema
resources and places them in the appropriate location in the A E S c h e m a s folder.
• When you configure a custom adapter, you create schemas inside the
A E S c h e m a s folder. You then add schema references to the services your
adapter provides. Some examples are given in this chapter.
You use this palette to define schema for your adapter. See Defining Custom
Adapter Schema on page 206 for an example.
Classes
Many TIBCO applications produce or consume data that are structured as objects.
These objects are described by schemas.
A Generic Class resource can be used for these purposes:
• Define a class object to represent schema data for your adapter. See Defining a
Class with Attributes on page 209 and Defining a Class with Operations on
page 212.
• Add a class field to your class object. See Adding Class Attributes on
page 210.
1. In the TIBCO Designer project tree, select the A E S c h e m a s folder, then the a e
folder.
2. Drag a F o l d e r resource into the a e folder displayed in the design panel and
name it appropriately for your adapter.
3. Drag an A E S c h e m a resource into the folder. Open the A E S c h e m a resource and
select its C l a s s e s folder.
4. In the palette panel, select the Generic Class icon and drag it into the design
panel.
5. For the C l a s s Type field, select S c h e m a , then click Apply.
6. You can now add attributes to the class. If you are using palette view, you
must select the appropriate palette before you can proceed.
You cannot add attributes to a class until you have specified its type.
1. Specify the class that should restrict the attribute value, if it does not yet exist.
2. Select the class to which you want to add the attribute, or drag a Generic
Class into the design panel and choose Schema as the type.
3. With the Schema class selected, drag the class that should restrict the value
into the design panel (or click the Browse button with the class field selected).
4. Click Apply.
See How TIBCO Applications Use Schema Data, page 203 for more information.
1. Specify the union that should restrict the attribute value, if it does not yet
exist. Add union members.
2. Select the class to which you want to add attributes, or drag a G e n e r i c Class
into the design panel and choose Schema as the type.
3. Drag the Union resource into the design panel.
You have now specified that union is the choices of attribute values. For
example, you could drag both a string and an integer.
4. Click Apply.
See Unions, page 218 for more information.
To add an attribute of type sequence, you must have first defined a sequence.
1. Specify the sequence that should restrict the attribute value, if it does not yet
exist.
2. Select the class to which you want to add attributes, or drag a G e n e r i c Class
into the design panel and choose Schema as the type.
3. Drag a Generic Sequence from the Sequence Types palette into the design
panel.
4. Specify a Name, Element Type, and length for your sequence. The length is
the number of elements in the sequence.
5. Click Apply.
See Sequences, page 221 for more information.
1. Specify the scalar that should restrict the attribute value, if it does not yet
exist.
2. Select the class to which you want to add attributes, or drag a G e n e r i c Class
into the design panel and choose Schema as the type.
3. Drag a Generic Scalar from the Scalar Types palette into the design panel.
4. Specify a name, then bring up the pop-up to specify the type of scalar.
The values you can choose from are the types available as part of the Adapter
SDK class library. See the TIBCO Adapter SDK Programmer’s Guide for
information on the mapping of these types to Java or C++ types.
5. Specify other information as appropriate, then click Apply.
1. In the TIBCO Designer project tree, select the A E S c h e m a s folder, then the a e
folder.
2. Drag a Folder resource into the a e folder displayed in the design panel and
name it appropriately for your adapter.
3. Drag an A E S c h e m a resource into the folder. Open the A E S c h e m a resource and
select its C l a s s e s folder.
4. In the palette panel, select the G e n e r i c Class icon and drag it into the design
panel.
5. For the C l a s s Type field, select O p e r a t i o n Schema, then click Apply.
6. You can now add operations to the class (see Adding Operations to an
Operation Class on page 212). If you are using palette view, you must select
the appropriate palette before you can proceed.
You cannot add attributes to a class until you have specified its type.
2. From the palette panel, drag the O p e r a t i o n icon into the design panel, then:
a. Name the operation
b. Click Browse and select the resource that specifies the return type. It
could, for example, be a resource in the A E S c h e m a / a e / S c a l a r s folder or a
predefined class.
c. Click the O n e Way check box if this is a one way operation.
3. Select the p a r a m e t e r s folder and drag resources representing the parameter
type into the design panel. For example, assume you want to specify an input
parameter of type string:
a. Drag a G e n e r i c Scalar into the design panel.
b. Specify a name, the type (S t r i n g ), and optional direction (I n ).
I n —In parameter. Client can set the value and invoke the operation.
I n / O u t —Both client and server can set the value.
O u t —Only server can set the value and send the reply back to client.
c. Click Apply.
d. Specify additional parameters by repeating steps a-c as desired.
4. Select the E x c e p t i o n s folder and drag a resource representing the exception
type into the design panel. For an error code, you could use a scalar with the
appropriate type. You could also specify a class, as follows:
a. Drag a G e n e r i c Class into the design panel.
b. Specify a name and click Browse to select a class.
c. Choose A E S c h e m a s / a e / M A d v i s o r y D o c u m e n t to indicate this exception
returns an M A d v i s o r y D o c u m e n t instance.
d. Click Apply.
e. Specify additional exceptions by repeating steps a-d as desired.
Operations
SDK operations are described in the metadata objects in the repository. The
operation description can be shared across TIBCO ActiveEnterprise products and
introspected at run time for dynamic invocation.
Implementing ActiveEnterprise operations consists of two tasks:
Defining Operations
To define an operation, follow these steps:
1. In the TIBCO Designer project tree, select the A E S c h e m a s folder, then the a e
folder.
2. Drag a Folder resource into the a e folder displayed in the design panel and
name it appropriately for your adapter.
3. Drag an A E S c h e m a resource into the folder. Open the A E S c h e m a resource and
select its C l a s s e s folder.
4. In the palette panel, select the G e n e r i c Class icon and drag it into the design
panel.
5. For the C l a s s Type field, select O p e r a t i o n Schema, then click Apply.
6. Select the O p e r a t i o n S c h e m a class in the project tree. From the palette panel,
drag an O p e r a t i o n into the design panel.
7. Specify the following information for the operation:
Name. Define the operation name.
Returns: Click Browse and select the return type for the operation. It could,
for example, be a resource in the A E S c h e m a / a e / S c a l a r s folder or a
predefined class.
Oneway. Click this check box if the operation can be invoked without waiting
for a return value or acknowledgment.
8. Select the P a r a m e t e r s folder of the operation. From the project tree, drag in
the resources representing the parameter types. See Defining Operation
Parameters on page 214.
9. Select the E x c e p t i o n s folder of the operation. From the project tree, drag in
the resources representing the exception types.
Your operation now expects a parameter which has the union you selected as its
type.
Scalars
Within TIBCO Designer, the term Scalar refers to a primitive object that describes
a data type, such as i n t , l o n g , c h a r , b y t e , and d a t e . You select the appropriate
folder (for example, ae or sql) and object to determine what kind of primitive data
type describes the object and which attributes must therefore be set.
The resources in the ae folder correspond to the types available for SDK adapters.
2. From the palette panel, drag a G e n e r i c Scalar into the design panel.
3. In the configuration panel, specify the information about the scalar, then click
Apply.
To add a scalar attribute to a custom class:
Unions
Unions may be placed alongside classes within a Classes folder. Like classes,
unions are containers of data items, but the contents of a union are alternatives.
Only one alternative is actually present in the union instance. Like classes, unions
may have an associated property list.
Unions have a name and have one or more union members. Each union member,
in turn, has a name and a type. Union and union member elements may have
attributes.
You can add more than 2 class references as union members. You can also mix
class references and other references.
2. From the project tree, drag an existing sequence into the design panel. See
Sequences on page 221.
TIBCO Designer creates a reference to the sequence.
3. From the project tree, drag an second sequence into the design panel.
TIBCO Designer creates a reference to the second sequence.
4. If you now add the union as an attribute to a schema class and assign that
schema to an endpoint, the endpoint will only accept data that either match
one or the other sequence.
You can add more than 2 sequence references as union members. You can also mix
sequence references and other references.
3. From the project tree, drag a second union into the design panel.
TIBCO Designer creates a reference to the second union.
4. If you now add the union as an attribute to a schema class, and assign that
schema to an endpoint, the endpoint will only accept data that match either
one or the other union, that is, any of the elements in either union.
You can add more than 2 union references as union members. You can also mix
union references and other references.
Sequences
Sequence objects describe ordered sets of the same type, for example, an ordered
set of integers. The sequence is described by its optional maximum length and the
type of element in the sequence. Because the sequence is parameterized both by
length and element type, there are an infinite number of sequence types.
Create a sequence as follows:
Associations
An association has two endpoints and each association has attributes such as
multiplicity and navigability.
Association Types
To better support mapping to relational databases, the XML standard defines an
association type, which is one of the following:
• CONTAINMENT. Implies that an instance of class A "owns" one or more
instances of class B. No other class has ownership of the same B instance. If
class A is deleted, logically the B instance should be deleted also.
• REFERENCE. An instance of class A is associated with zero or more instances
of class B. The B instances may be referenced by more than one instance of A.
This is the most general form of association and is the default if no type is
specified.
A Note on Multiplicity
Both ends of an association can have a multiplicity. For example, a 1 to 1 relation
has multiplicity = 1 on both ends. One to n (i.e. unlimited) has 1 at one end and -1
(unlimited) on the other. In these cases, there is only one multiplicity number and
m i n M u l t i p l i c i t y and m a x M u l t i p l i c i t y will be equal.
In rather rare cases, you would specify a different minimum and maximum. One
example given in the "UML Distilled" book is that a car can have 2 to 4 doors. So
in this case the "car" end of the association would have multiplicity 1 and the
"door" end would have m i n M u l t i p l i c i t y = 2 and m a x M u l t i p l i c i t y = 4.
See any reference on UML for more details.
This section lists resources created by TIBCO Designer under certain special
conditions. The section is not meant to be read sequentially, instead, it is accessed
by the online help when you click "What is this" on any of the resources. You may
also find it helpful when you are interested in information about a specific
resource.
• Class Reference
• Scalar Reference
• Union Reference
• Sequence Reference
• Generic Class
• Generic Scalar
• Generic Union
• Generic Sequence
• Class Field
• Scalar Field
• Union Field
• Sequence Field
Class Reference
TIBCO Designer creates a schema class reference in these situations:
• When you add a class to a union as a union member. See Adding Class
Reference Union Members on page 219.
• When you add a class as an exception to the Exceptions folder of an operation.
See Defining Exception Parameters on page 217.
• When you add a class to an endpoint to restrict the data it should work with.
See Defining Custom Adapter Schema on page 206.
Scalar Reference
TIBCO Designer creates a scalar reference in these situations:
• When you add a scalar to a union as a union member. See Adding Scalar
Reference Union Members on page 220.
• When you add a scalar as an exception to the Exceptions folder of an
operation. See Defining Exception Parameters on page 217.
• When you add a scalar to an endpoint to restrict the data it should work with.
See Defining Custom Adapter Schema on page 206.
Union Reference
TIBCO Designer creates a union reference in these situations:
• When you add a union to a union as a union member. See Adding Union
Reference Union Members on page 220.
• When you add a union as an exception to the Exceptions folder of an
operation. See Defining Exception Parameters on page 217.
• When you add a union to an endpoint to restrict the data it should work with.
See Defining Custom Adapter Schema on page 206.
Sequence Reference
TIBCO Designer creates a sequence reference in these situations:
• When you add a sequence to a union as a union member. See Adding
Sequence Reference Union Members on page 219.
• When you add a sequence as an exception to the Exceptions folder of an
operation. See Defining Exception Parameters on page 217.
• When you add a sequence to an endpoint to restrict the data it should work
with. See Defining Custom Adapter Schema on page 206.
Generic Class
A generic class is a resource template in the palette panel that you can drag into
the design panel. The actual resource TIBCO Designer creates from the generic
class depends on the current selection.
• If the current selection is any of the folders or subfolder inside the AESchemas
folder, TIBCO Designer creates a generic class. You can then select the class
type (Schema or Operation class) and TIBCO Designer creates a resource of
that type. See How TIBCO Applications Use Schema Data on page 203.
• If the current selection is a Schema class, the Generic class becomes a Class
field, that is, a field inside the class that has that class as the type. See Adding
Class Attributes on page 210.
• If the current selection is a Union or the Exceptions folder inside an operation,
TIBCO Designer creates a class reference. See Class Reference on page 223.
Generic Scalar
A generic scalar is a resource template in the palette panel that you can drag into
the design panel. The actual resource TIBCO Designer creates from the generic
scalar depends on the current selection.
• If the current selection is any of the folders or subfolder inside the AESchemas
folder, TIBCO Designer creates a Scalar Type resource. See Scalars on
page 217.
• If the current selection is a Schema class, the Generic sequence becomes a
Union field, that is, a field of type Union inside the class. See Adding Union
Fields on page 211.
• If the current selection is a Union or the Exceptions folder inside an operation,
TIBCO Designer creates a union reference. See Union Reference on page 224.
Generic Union
A generic union is a resource template in the palette panel that you can drag into
the design panel. The actual resource TIBCO Designer creates from the generic
union depends on the current selection.
• If the current selection is any of the folders or subfolder inside the AESchemas
folder, TIBCO Designer creates a Union Type resource. See Unions on
page 218.
• If the current selection is a Schema class, the Generic sequence becomes a
Union field, that is, a field of type Union inside the class. See Adding Union
Fields on page 211.
• If the current selection is a Union or the Exceptions folder inside an operation,
TIBCO Designer creates a union reference. See Union Reference on page 224.
Generic Sequence
A generic sequence is a resource template in the palette panel that you can drag
into the design panel. The actual resource TIBCO Designer creates from the
generic sequence depends on the current selection.
• If the current selection is any of the folders or subfolder inside the AESchemas
folder, TIBCO Designer creates a Sequence Type resource. See Sequences on
page 221.
• If the current selection is a Schema class, the Generic sequence becomes a
Sequence field, that is, a field of type Sequence inside the class. See Adding
Sequence Fields on page 211.
• If the current selection is a Union or the Exceptions folder inside an operation,
TIBCO Designer creates a sequence reference. See Sequence Reference on
page 224.
Class Field
TIBCO Designer creates a class field when you drag a Class into the design panel
while a schema resource is selected. See Adding Class Attributes on page 210.
Scalar Field
TIBCO Designer creates a scalar field when you drag a Scalar into the design
panel while a schema resource is selected. See Adding Scalar Fields on page 211.
Union Field
TIBCO Designer creates a union field when you drag a Union into the design
panel while a schema resource is selected. See Adding Union Fields on page 211.
Sequence Field
TIBCO Designer creates a sequence field when you drag a Sequence into the
design panel while a schema resource is selected. See Adding Sequence Fields on
page 211.
This section briefly discussed TIBCO Designer Adapter Schema folders. The
appendix is not meant to be read sequentially, instead, it is accessed by the online
help when you click "What is this" on any of the folders. You may also find it
helpful when you are interested in information about a specific folder.
Folder Resource
Folder resources are used to organize projects. For example, you can add one
folder each for each adapter instance you are designing. TIBCO Designer uses
folders inside the A E S c h e m a s folder to organize Schema resources.
AESchemas Folder
The A E S c h e m a s folder is a container for all schema data used by all applications in
your project.
• When you configure a standard adapter, TIBCO Designer creates schema
resources and places them in the appropriate location in the AESchemas
folder.
• When you configure a custom adapter, you create schemas inside the
AESchemas folder. You then add schema references to the endpoints in your
application. Some examples are given in this chapter.
Classes Folder
The Classes folder is a container for all classes used by all applications in your
project. Create a folder for you application inside this folder for a clean
organization. See the TIBCO Adapter SDK Programmer’s Guide for more
information.
Scalars Folder
The S c a l a r s folder is a container for all scalars used by all applications in your
project. It contains folders for scalars commonly used by applications.
• The S c a l a r s folder under A E S c h e m a s / a e contains TIBCO ActiveEnterprise
scalars. For information on mapping between those scalars and C++ and Java
types, see the TIBCO Adapter SDK Programmer’s Guide.
• The S c a l e r s folder under A E S c h e m a s is meant to hold a folder for the scalars
used as schema by your application.
For more information, see Scalars on page 217
Unions Folder
The U n i o n s folder is a container for all unions used by all applications in your
project. Create a subfolder to hold unions used by your project. For more
information, see Unions on page 218
Sequences Folder
The S e q u e n c e s folder is a container for all sequences used by all applications in
your project. Create a subfolder to hold sequences used by your project. See the
TIBCO Adapter SDK Programmer’s Guide for more information.
For more information on using sequences inside TIBCO Designer, see Sequences
on page 221
Associations Folder
The A s s o c i a t i o n s folder is a container for all associations used by all
applications in your project. For more information, see Associations on page 221.
i
You cannot use the R e p o s i t o r y palette and associated R e p o s i t o r y Finder to
manage multi-file projects.
Topics
Introduction
TIBCO Designer offers two paradigms for manipulating data: projects and
repositories. In most cases, you use the project paradigm. In some cases, you want
to look at or work with the underlying paradigm, the repository. You can locate,
manage, and monitor repositories using the repository palette.
This chapter first compares the two paradigms. It then explains how to display
the repository palette, and how to use TIBCO Designer to locate repository
instances. It also gives a reference to all icons in the Repository palette.
You can use Repository Finder only to manage 4.x repositories. It does not work
for 5.x multi-file projects (VC format repositories).
This chapter gives an introduction to projects and repositories and how they
interact.
• Projects and Repositories
• Showing the Repository Palette
• Repository Finder Tool
• Using Repository Finder to Locate Repositories
• Repository Palette
You can view and manipulate any repository using Repository Finder. This
includes repositories saved as projects from TIBCO Designer and legacy
repositories created by other tools. You can also view and manipulate currently
loaded projects as repositories.
Warning: In almost all cases, it is appropriate to work with your data using the
project’s folders, resources, and configuration information. One reason for this is
that TIBCO Designer makes sure the public and private repository areas are in
sync when you edit a project. Inconsistencies may result if you change a
repository using Repository Finder.
The Repository Finder hierarchy is meant for certain administrative tasks on
legacy projects and not usually used for application design.
You can only locate repositories that have been saved in . d a t format. You cannot
locate repositories for multi-file projects.
1. Make sure the Repository palette is available (not hidden). See Showing the
Repository Palette on page 231.
2. Drag a Repository Finder from the palette panel to the design panel.
A Repository Finder is added to your project and displayed in the design
panel and the project tree. The configuration panel lets you specify discovery
criteria.
TIBCO Designer looks for repositories in the specified directory and displays
them in the project tree panel under a Local Repositories entry. Here’s an
example of part of a repository hierarchy for a TIBCO BusinessConnect for
RosettaNet application.
e. If you want to look for both local and remote repositories, go on to the next
step.
Servers and 4. Click Server Repositories if you want to find repository servers and their
Instances instances.
a. Click the Search Remotely check box.
b. If the server is using RVD, specify any non-default TIBCO Rendezvous
daemon, network, and service, specify it here. Otherwise, TIBCO Designer
searches using the defaults, which are:
— RV Daemon: tcp:7500
— RV Network: unspecified
— RV Service: unspecified
c. If you are using RVA, click the RVA button and specify the host and port.
5. Browse the local and remote repositories that match your search criteria. In
the hierarchy, you see repository instances, directories, and objects.
Repository instance
Repository directory
Repository object
The repository hierarchy in the project tree panel allows you to view repository
servers, instances, directories, and objects. This section gives a brief overview of
what you see.
Repository server
Server-based instance
Local instance
At the first level of the hierarchy, you can see the following items:
Repository Server
A repository server manages repository instances. The instances can be local or
remote, and can be files or stored in a database. The server uses TIBCO
Rendezvous software to communicate with remote clients.
A repository server can support multiple remote repository instances. A
repository server is identified by a name which must be unique among all
repository servers on a network. The repository server communicates with
repository instances via TIBCO Rendezvous.
Server-based Instance
A server-based instance can be on any computer on the network and can be in a
file or a database.
Local Instance
A local instance is always a . d a t file and accessed directly, not via TIBCO
Rendezvous.
Repository directory
Repository object
Repository Palette
When you select Repository Finder or one of the resources below it in the project
tree hierarchy, the Repository palette is displayed in the palette panel. Depending
on the selected resource, you can either add a repository instance or a repository
directory and object to the design panel.
Repository Instance
A repository instance is a named collection of data, usually metadata and
configuration data that is persistently stored. A local repository instance is stored
on the local file system and directly accessed by the client. A remote repository
instance is managed by a repository server and accessed by a client using TIBCO
Rendezvous.
See Introduction on page 230 for information on the operations you can perform.
Repository Directory
A repository directory is a container for one or more directories as well as one or
more objects. Directories are used for organizing objects so that they can then be
referred to unambiguously.
Repository Object
A repository object is a container for the data. Data are organized as an ordered list
of name:value pairs called an association list. In effect, an object is a named
association list. The term object is used although there is no notion of inheritance
or information hiding, nor does the object have any methods.
3. Specify the instance name, display name, and file type as prompted.
TIBCO Designer creates a repository instance and displays it under Local File
Repositories.
4. If you like, you can specify additional information. See Specifying Additional
Repository Information on page 241
If you like, you can specify additional information. See Specifying Additional
Repository Information on page 241.
Encoding Specify the encoding you intend to use for this project’s encoding property. This
property is used by client applications that access the project for any TIBCO
Rendezvous communications. For example, if a TIBCO Adapter accesses the file, it
will then use the value specified in this Encoding property for TIBCO Rendezvous
communication with other applications.
Note that this is not the encoding of the repository's persistent storage.
Legal values are ISO8859-1 (for Latin-1 and ASCII 7-bit character sets) and UTF-8
(for other non-Latin-1 and Asian character sets).
The following information is included in the General tab but cannot be changed.
Version Shows the version for this repository (cannot be changed). Default for TIBCO
Designer 4.0.0 repositories is 4.0.0.
Instance Either LocalFile for a local file repository or remoteRV for any repository managed
Type by a server.
1. In the project tree, right-click the repository instance you want to clone.
You can clone either a local or a remote repository.
You are prompted for information about the new repository. For local file
repositories:
After you stop a repository server, no one on your network can view or modify
repository instances associated with that server.
4. The repository is displayed below the selected server or below Local File
Repositories.
You can change the content of a repository in several ways, discussed in this
section.
• Exporting and Importing Repository Instances
• Adding TIBCO Repository Directories and Objects
• Advanced Repository Management
• Advanced Repository Management
Exporting an Instance
To export a repository instance, follow these steps:
Importing an Instance
To import a repository instance, follow these steps:
4. Click Yes to replace the contents. In that case, TIBCO Designer first completely
empties the existing repository instance and then imports all information from
the file.
5. Click No if you want to partially replace the existing repository. In that case,
TIBCO Designer prompts you whether duplicates should be replaced:
— If there are duplicate repository directories, you can replace or reject a
whole directory and its contents.
— If there are duplicate repository objects, you can replace or reject the object
and its contents.
1. Browse the repository to select the directory for which you want to add a
subdirectory.
2. From the repository palette, drag a directory resource template into the design
panel.
3. Rename the directory, then double-click it to open it.
4. From the repository palette, drag an object resource template into the design
palette.
You are adding an object to the newly created directory.
5. Rename the object.
6. If you want to add attributes to the object, you must first turn on the advanced
editing and browsing options. See Advanced Repository Management,
page 247.
You cannot delete the root node or add a root node. All repositories have exactly
one root node and directories and objects can only be added below that root node.
You can specify a user and password, and turn on advanced browsing and editing
to access and change attribute values. Follow these steps:
Object
Attribute
TIBCO Designer displays the object and its attributes. Attributes usually have
names, attribute types, and other properties. The value of each attribute is
either a string or a global name. In the example above, the attribute with the
name s t a t u s M s g has an a t t r i b u t e T y p e that is a global name.
In almost all cases, it is preferable to modify the attributes as part of the resources
in a project. However, if you are working with an adapter that has custom objects,
you may need to use the Repository Finder capabilities.
Terminology
Keep in mind the following terminology used to describe repository content.
• An object contains attributes.
• An attribute is a named association list. As a result, you add an association list
to an object, then name it and have an attribute.
• The name:value pairs inside the association lists are called properties of the
attribute. For example, name, a t t r i b u t e T y p e , and i s K e y are properties of the
attribute. Custom properties are also allowed.
Steps
To modify an attribute, follow these steps:
1. Locate the repository in which you want to make changes. See Introduction on
page 230.
2. In the configuration panel, click Advanced, then select the Advanced
Browsing and Advanced Editing check box and click Apply.
3. In the project tree panel, find the repository object in which you want to add
or change attributes.
4. When you select the object
— the object is displayed in the configuration panel
— edit buttons for the configuration panel are displayed at the bottom of the
panel (see below)
— you can select the named association lists and their properties
5. To change the value of a property inside an attribute, triple-click the property
to select it, then type the new value into the edit field that opens. In the screen
shot below, the d e f a u l t S t a r t u p property of the startup attribute is being
edited.
up/down
delete
association list
load file into a byte array (file => byte array)
binary
save the value of a binary property
reference into a file (byte array => file)
string
Icon Description
Binary icon Click the binary icon to add a property a byte array
stored in a file. After you’ve added the binary, you can
click the file => byte array or byte array => file icons
Byte array => File Copies a byte array into a file (on disk) and saves the
file. It does not remove the byte array value from the
binary property.
Icon Description
You must click Commit to save changes before selecting another resource or your
changes are lost.
You can click Rollback to undo changes since the last commit.
You can also move properties by clicking the up/down icon, and delete them by
clicking the delete icon.
This section is a reference to menu items and toolbar items that are available when
you work with Repository Finder, or with items inside it.
Other menus and icons are discussed in TIBCO Designer User’s Guide, available if
you select Help > Designer Help, or in the documentation for other TIBCO
products you installed.
Create Repository Prompts you for information about the repository instance
Instance you wish to create. See Creating Repository Instances on
page 239.
Start Repository Prompts you for the name of an instance to start. (Not
Instance available from Local File Repositories icon).
Stop Repository Stops the selected (Not available from Local File
Server Repositories icon).
Toolbar Icons
When you select a repository instance, three icons are added to the toolbar that
allow you to perform actions also available from the instance’s right-button
menu.
Index
V
viewing attributes 249
X
XA control pool 186
XML
introduction 14
XML file 254
XML instance editing environment 119
XML instance exercise 137
XML menu 120
XML menu (instance resources) 30
XML resource 15
XML schema exercises 70
XML tools palette
getting started 15
XML tools palette resources
common table columns 27