tibco designer palettes

TIBCO Designer™Palette ReferenceSoftware Release 5.6July 2008

Important InformationSOME 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

Chapter 1 General Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

AliasLibrary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Enterprise Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Generic Image Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Certificate/Private Key Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Identity File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Username/ Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

LibraryBuilder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Task List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Text Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 2 XML Tools Palette. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Introduction to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Getting Started with the XML Tools Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Creating a New Resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Getting Started with Schema and DTD Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Getting Started with Instance Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Common Columns In Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Toolbar Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Menu Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

TIBCO Designer Palette Reference

iv | Contents

Content Model Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Schema Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Schema Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Elements/Types Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Elements/Types List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Content Model Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Attributes Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Overview Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Advanced Panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Simple Types Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Schema Props Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Validations Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Component Doc Panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Source Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

XML Schema Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Exercise 1: Building a Simple Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Exercise 2: Defining and Deriving Complex and Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Configuration Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Schema Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Elements Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84The Element List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84The Content Model Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Attributes Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Overview Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Advanced Panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Schema Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Errors Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Notes Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Source Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

DTD Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Configuration Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120XML Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Setting a Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Content Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Content Panel: Tag Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122


Contents | v

Content Panel: Edit Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Errors Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Source Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

XML Instance Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Building Your Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Customizing and Populating Your Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Chapter 3 Adapter Resources Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Specifying Generic Adapter Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Configuring a New Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Adding Services to Your Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Advanced Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Adding Custom Log Sinks to Your Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Adding Extended Properties to Your Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Adding Custom Hawk Microagents to Your Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150A Note on Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Using a Message Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Testing Your Adapter Using Adapter Tester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Generic Adapter Configuration Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Monitoring Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Services Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Subscription Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Custom Log Sink Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Log Sinks Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170File Sink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171stdio Sink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Network Sink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Hawk Sink. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Adding Roles to Sinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Sessions Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174RV Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175RVA Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175RVCM Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176RVCMQ Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177RVTX Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179


vi | Contents

JMS Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Transaction Control and Advisory Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Transaction Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Advisories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Folder Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Adapter Services Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Advanced Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Log Sinks Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Sessions Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Timers Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Transaction Controls Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Advisories Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Metadata URLs Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Endpoint Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Endpoints Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Publisher Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Subscriber Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Client / Request-Response Invocation Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Server / Request-Response Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Adding Schema to Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Chapter 4 Adapter Schema Palette. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Understanding Schema Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Managing Schema for Standard Adapters With Custom Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Managing Schema for Adapters that Are Loaded Into GAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Managing Schema for Custom Adapters Created with the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203How TIBCO Applications Use Schema Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Configuring Standard Adapter Endpoints and Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Defining Custom Adapter Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

TIBCO Designer Schema Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208AESchemas Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Adapter Schemas Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Defining a Class with Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Defining a Class with Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Associations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Schema Resource Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223


Contents | vii

Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Scalar Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Union Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Sequence Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Generic Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Generic Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Generic Union. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Generic Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Class Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Scalar Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Union Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Sequence Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

TIBCO Designer Adapter Schema Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Folder Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227AESchemas Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Classes Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Scalars Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Unions Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Sequences Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Associations Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Chapter 5 Repository Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Projects and Repositories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Showing the Repository Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Repository Finder Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Using Repository Finder to Locate Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Navigating the Repository Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Repository Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Managing Repository Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Creating Repository Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Specifying Additional Repository Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Cloning Repository Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Deleting Repository Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Stopping a Repository Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Starting or Stopping a Repository Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Managing Repository Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Exporting and Importing Repository Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Adding TIBCO Repository Directories and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Advanced Repository Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Viewing Attributes of Repository Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Modifying Attributes Inside Repository Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Menus and Toolbar Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253


viii | Contents

Repository Server Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Repository Instance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Toolbar Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255


| ix

Figures

Figure 1 Adding an XML Resource to your project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 2 Editing environment for Schema and DTD resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Figure 3 Instance editing environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Figure 4 Common table columns used by XML Tools palette resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Figure 5 Content Model Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Figure 6 Diagram for a sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Figure 7 Diagram for a choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Figure 8 Optional and repeatable set of choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Figure 9 All occurrence indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Figure 10 Mixed content model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Figure 11 All content model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 12 Element/Types panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Figure 13 Element/Type list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Figure 14 Completed content model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Figure 15 Content Model Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Figure 16 Attributes panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Figure 17 Overview panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Figure 18 Referencing an element from another namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Figure 19 Notations tab of the advanced pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Figure 20 Creating a new simple type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Figure 21 Graphical view of the schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Figure 22 Referencing a complex type in another schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Figure 23 A completed content model for a Book element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Figure 24 Content model editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Figure 25 Referencing a reusable (internal parameter entity) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Figure 26 Attributes panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Figure 27 Overview panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Figure 28 Enumerations tab of the properties pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103


x | Figures

Figure 29 Creating an internal parameter entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Figure 30 Referencing a parameter entity within a content mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Figure 31 Listing of external parameter entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Figure 32 Defining internal general entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Figure 33 Defining an external general entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Figure 34 Defining an external unparsed entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Figure 35 Notations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Figure 36 Graphical view of the schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Figure 37 XML instance editing environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Figure 38 Content panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Figure 39 Insert box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Figure 40 Factory bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Figure 41 Inserting a comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Figure 42 Right button menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Figure 43 Content hint as tool tip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Figure 44 Navigator bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Figure 45 Siblings displayed on navigator bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Figure 46 Item and type level (right-button) menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Figure 47 Selecting a hidden element to show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Figure 48 Specifying an alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Figure 49 Color options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Figure 50 Promoted elements and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Figure 51 Resizing rows to allow for additional promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Figure 52 Content hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Figure 53 Row format (the default view) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Figure 54 Markup format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Figure 55 Blue ellipsis icon for collapsing or expanding markup view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Figure 56 Content panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Figure 57 Document-building options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Figure 58 TIBCO Designer Generic Adapter Configuration Default Folders . . . . . . . . . . . . . . . . . . . . . . . . . 188


| xi

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Table 3 XML Tools panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Table 4 Toolbar buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Table 5 Schema menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Table 6 XML menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Table 7 Occurrence indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Table 8 Sequence indicators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Table 9 Properties tab fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Table 10 Occurrence indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Table 11 Sequence indicators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Table 12 Datatypes within a DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Table 13 Occurrence indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Table 14 Sequence indicators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Table 15 Cipher suite list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Table 16 Icons in Extended Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251


xii | Tables


| xiii

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, page xiv

• Typographical Conventions, page xv

• How to Contact TIBCO Support, page xvii


xiv | Related Documentation

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


Preface | xv

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin .

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname

Key combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For 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.


xvi | Typographical Conventions

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use

Table 2 Syntax Typographical Conventions

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

{ } A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1 and param2 , or the pair param3 and param4 .

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4 :

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1 . You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4 .

MyCommand param1 [param2] {param3 | param4}


Preface | xvii

How to Contact TIBCO Support

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.


http://www.tibco.com/services/support

https://support.tibco.com

xviii | How to Contact TIBCO Support


| 1

Chapter 1 General Palette

The General palette contains resources used by different TIBCO applications.

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


2 | Chapter 1 General Palette

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

AliasLibrary

The AliasLibrary resource allows you to specify aliases to file system resources (such as a .jar 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 | 5

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:

• Folders created from a Folder resource in the General palette, displayed with a multi-folder icon, become folders in the file system.

• Other folders, such as the Adapter Services folder inside an adapter configuration are logical folders. These folders only exist in memory in the resource that holds them. The actual data for these elements is stored in a file.



Generic Image Resource

The Generic Image resource allows you to associate a custom image with a predefined resource. This is useful, for example, if you have configured a Generic Adapter Configuration and you wish to represent it with a custom image.

To add an image to a project, follow these steps:

1. With the General palette displayed in the palette panel, drag a Generic Image resource into the design panel. You now have two choices:

a. Choose Built-in to associate one of the already available images (for example, a folder icon) with your image. Name the new icon, then choose Browse and select the corresponding (already loaded) image.

b. Choose Custom to specify an image name and the location where it is stored. You may select the Preview tab to preview the image.

To associate the image with a resource in the project, follow these steps:

2. Choose the View > Toggle Custom Icon Support menu.

3. When you select a resource, it now displays an Icon Reference field. Click Browse and select the icon.


Identity | 7

Identity

The Identity resource encapsulates information that may be used to authorize a user, connection, and so forth. The information you supply changes depending on the type of Identity resource you want to use.

The identity certificate location, its type, and password can be specified as global variables. Resources referencing an identity must use the same identity type because this is selectable from a pop-up and does not allow global variables.

Certificate/Private Key IdentityUse this option if the private key and the certificate are in two separate files.

Identity FileUse this option of the certificate includes the private key information in the same file.

Name Name of this identity resource.

Description Optional description.

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.

Key Password Password used for private key.



URL Location of the certificate (which includes the private key). 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.



Username/ PasswordUse 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:

File Type Choose the certificate from the pop-up.

Password Password for the certificate.



Username Name of the user for this identity.

Password Password for the user for this identity.


LibraryBuilder | 9

LibraryBuilder

The LibraryBuilder resource is used to build a design-time library, which allows resources you have defined in one project to be used in other projects. This allows you to create shareable resources once and then allow other project developers to use them in their projects.

For example, Rendezvous resources, JMS resources, schemas, and process definition libraries can be part of a design-time library.

See Creating a Design-time Library on page 98 in TIBCO Designer User’s Guide for details.



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 Project Tracker palette if in palette mode.

2. Drag a Task 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.

5. Drag tasks and task lists into the design panel as needed.

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.

Delete task. Deletes the selected task

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.


Task List | 11

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:

— Planned Start Date

— Planned Completion Date

— Estimated Worktime (hours)

— Actual Start Date

— Actual Completion Date

— Actual Worktime (hours)

— Progress

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.

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.



Text Document

The Text Document 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 Text Document , you can provide a name (which appears as the label) and the text.


| 13

Chapter 2 XML Tools Palette

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, page 14

• Getting Started with the XML Tools Palette, page 15

• Schema, page 37

• XML Schema Exercises, page 70

• DTD, page 82

• DTD Exercise, page 113

• Instance, page 119

• XML Instance Exercise, page 137


14 | Chapter 2 XML Tools Palette

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.


Getting Started with the XML Tools Palette | 15

Getting Started with the XML Tools Palette

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.

Creating a New ResourceTo add a new XML resource to your project, follow these steps:

1. Select a folder in the project panel.

The XML Tools palette becomes available. If the palette is not available

— Make sure you’re in palette mode by clicking the switch palette mode icon.

— Choose the Palettes > General > XML Tools menu and make sure XML Tools is checked.

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.

Figure 1 Adding an XML Resource to your project

FeaturesWhen 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

For additional information on basic interaction with TIBCO Designer and on customizing your GUI, see TIBCO Designer User’s Guide.

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



• Intuitive properties panel facilitating the application of advanced schema concepts such as data type constraints and substitution groups (XML Schema only)

• Component and schema level documentation

• Tools for including other schemas and/or schema components when building a new schema

• A Source view for directly editing the source code

Getting Started with Schema and DTD ResourcesYou can access the schema editing panels by using a set of toolbar buttons or the Schema menu. The available tools combine to present a consistent view of your schema. Figure 2 illustrates the editing environment for Schema and DTD resources.

Because a DTD is not as feature-rich as an XML Schema, the editing environment for an XML Schema and a DTD is similar, but not identical. With a few exceptions, the DTD interface supplies a subset of the functionality provided by the Schema interface.



Figure 2 Editing environment for Schema and DTD resources

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.

Example: Creating a Schema

For example, to create an element called Book for a schema describing the structure of a book (which may contain elements such as a title , author, chapters , sections , glossary, index , and so on), follow these steps:

1. Drag a Schema 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 Element column and replace root with Book .

Names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods.

3. Ignore the Derives From column for now as this declaration will not be derived from an existing complex type definition.

Properties Panel

Configuration Panel

Content Model Diagram

Elements/Types Panel



4. Tab to the Content column and select the appropriate content type from the Content Type button. In this example, the content for Book will contain other elements (such as Chapter), so select Elements .

5. Tab to the Content Model column and type in the content model of the book. A simple content model for Book might look like the one shown below. See



Elements/Types Panel on page 40 and Example: Building a Content Model on page 46, for more information on how to build a content model.

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 Create new elements as Locally defined and click Create.

By default, new elements are declared to have xs:string content, which means they can hold text, but not other elements.

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 title that appears within a book element and another local element named title that appears within a mortgage element. Global elements are declared such that they can be referenced within any content model. All global elements must have unique names.



7. Click Create to create the elements.

8. Tab to the Attributes column for the element's row and type in attributes for the element. For example, the element Chapter may include attributes that give us more information about a chapter, such as its chapter number and chapter title.

If an attribute is as yet undefined, it is automatically created with data type xs:string . These attributes can be seen and modified in the Attributes Panel. See Attributes Panel on page 50 for more information.

The figure below illustrates the elements declared in this example.

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 Instance resources is provided in Table 3 on page 24.

Getting Started with Instance ResourcesWhen an Instance resource is selected within the project panel, a new set of panels appears, providing an interface for creating and navigating the resource. Features include:

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.



• Document-building guidance based on the rules defined in an XML Schema or DTD

• Validation against an XML Schema or DTD

• Source view enabling direct edits to the source code

• Multiple customized displays of an XML document

The new panels, in addition to new toolbar buttons and menu options, facilitate the schema-driven creation, editing, and management of data-oriented XML documents, messages, and configuration files. The next diagram illustrates the editing environment for instance resources.

Figure 3 Instance editing environment

The interface is optimized for XML documents based on a schema, so associating your document with a schema in your project is typically the first step. For example, to create an instance of an invoice schema:

1. Drag an Instance resource into the design panel and double-click it to select it.

2. Click the Set Schema button on the toolbar.

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.

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

Edit areaTag area

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.



schema's content models also appear in the insert drop down box, and can be added with a single mouse click.

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 Instance resources is provided in Table 3 on page 24.

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

insert as sibling

insert as parent

insert as child

insert new elementinsert new attribute

insert new processing instruction

insert new comment

insert new text

insert schema-definedelement or attribute

A detailed, step-by-step XML instance building exercise is included at the end of the Instance chapter. See XML Instance Exercise on page 137.

Table 3 XML Tools panels

Panel Resource Description

Configuration All The configuration panel is used for setting the XML resource name. For more information on the configuration panel, see:

• Schema Properties Panel, page 38 (Schema)

• Configuration Panel, page 82 (DTD)

• Configuration Panel, page 120 (Instance)



Source All The source panel allows you to edit the source code of your XML resource directly. For more information on the source panel, see:

• Source Panel, page 69 (Schema)

• Source Panel, page 112 (DTD)

• Source Panel, page 136 (Instance)

Validation or Errors

All The errors or validation panel displays warnings and 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 and DTD

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. 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 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). For more information on the content panel, see Content Panel, page 121.

Attributes Schema and DTD

The attributes panel is used to view, create, and edit attribute type declarations. For more information on the attributes panel, see:

• Attributes Panel, page 50 (Schema)

• Attributes Panel, page 93 (DTD)





Common Columns In TablesSeveral panels use tables to display the declarations within a schema. Figure 4 illustrates the first two columns that many tables share.

Overview Schema and DTD

The overview panel is used to control the creation of schemas that use XSD Includes, XSD Imports and DTD System Entities (modules), as well as explore the overall organization of your schema. For more information on the overview panel, see:

• Overview Panel, page 53 (Schema)

• Overview Panel, page 100 (DTD)

Properties Schema and DTD

The properties panel is used to associate properties or constraints with a selected declaration. For more information on the properties panel, see:

• Properties Panel, page 58 (Schema)

• Properties Panel, page 102 (DTD)

Advanced Schema and DTD

The advanced panel is used to define or edit parts of XML 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 or Notes

Schema and DTD

The component doc or notes panel provides an area where you 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)





Figure 4 Common table columns used by XML Tools palette resources

• 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 ButtonsWhen editing or viewing XML Tools resources, additional buttons appear on the toolbar. The toolbar buttons are described in Table 4.

Row Selector/Error Indicator Column Included Document Indicator Column

Table 4 Toolbar buttons

Toolbar Button Resource Function

All Checks the resource for errors and reports the results in the errors panel.

All Opens the source panel. If the button is dimmed, the panel is already open.

Schema and DTD Opens and closes the overview panel.

Schema and DTD Opens and closes the properties panel.



Menu OptionsWhen 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 menu (Schema and DTD resources)

A Schema menu becomes available when editing a Schema resource. The Schema menu contains two submenus, View and Tools (or Edit).

• The View menu provides options to control the panels used for editing, organizing, and viewing your schemas.

• The Tools (or Edit) menu includes options for searching or editing your schema, checking your schema for errors, and defining reusable schema components.

Schema and DTD Opens the elements/types panel. If the button is dimmed, the panel is already open.


Schema Opens the simple types panel. If the button is dimmed, the panel is already open.

Schema and DTD Opens the attributes panel. If the button is dimmed, the panel is already open.

Instance Opens the content panel.

Instance Allows you to associate a schema from your project with your instance document.

Instance Allows you edit your schema. Apply your changes to have them reflected in the content panel for the Instance resource.

Table 4 Toolbar buttons

Toolbar Button Resource Function



Table 5 describes the Schema menu.

Table 5 Schema menu options

Menu Option Description

Schema > View Schema Properties Opens the schema properties panel.

Schema > View Overview Opens or closes the overview panel.

Schema > View Properties Opens or closes the properties panel.

Schema > View Element/Types Opens the element/types panel. If the option is dimmed, the panel is already open.


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 Doc

Opens or closes the notes or component doc panel.

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.



XML Menu (Instance resources)

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.

Schema > View Diagram Attributes Displays or hides attributes in the content model diagram.

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 or Edit

Find Enables you to search for text in the active window. Select this option for the initial search.


Find Again Searches for the next occurrence of the text previously entered in the Find dialog box.


Replace Used to search and replace text in the active window. Replace is used for the initial search-and-replace.


Replace Again Searches and replaces the next occurrence of the text previously entered in the Replace dialog box.

Table 5 Schema menu options




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

Table 6 XML menu options


XML > Tools Insert Enables you to insert an element, attribute, comment, or processing instruction.

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 Content Hints Toggles on or off content hints that are displayed at half-intensity ('grayed-out') in the edit area to the right of certain elements or attributes. 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 Labels/Indent Labels

Choosing this option will left-align all tags and markup icons in the tag area. When Align Labels is 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 Listing)

A listing of the previously defined presentations. The 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.

XML > Presentation Remove Removes the selected presentation.

Table 6 XML menu options




Content Model DiagramThe content model diagram of the elements/types panel graphically displays the content models in a Schema or DTD resource. It presents the relationships between elements (that is, parent elements, child elements, and so on) with diagrams and provides additional information about elements, such as their attributes and occurrence and sequence within a content model. You can use the content model diagram to read, explore, or edit your schemas.

Reading the Content Model Diagram

To view a content model, click the appropriate element in the element/type list (below the diagram). The content model diagram is updated to reflect the currently selected element or type's content model. The content model diagram uses a visual vocabulary to represent complex element content models.

Elements are displayed as objects (in boxes) within the content model diagram. The boxes contain element names, data type indicators, and occurrence indicators. An element’s content model may be composed of text, other elements, text and elements, data, or none of these (as defined in the element definition). The icons used in the content model diagram are illustrated in Figure 5.

Figure 5 Content Model Diagram

Element icon

Element content

Occurrence indicator (Optional & repeatable)

Type content indicator

Occurrence indicator (optional)

indicatorType name

Attribute icon



If an element’s content model includes other elements (as indicated by the element content icon), the child elements may also be displayed in the content model panel. To view an element’s children, click once on the parent element’s content indicator icon to expand its tree. To collapse the tree and hide the child elements, click on the parent element object again.

Sequence indicator symbols do not appear in the content model diagram, but they are implied. Sequence content models are represented by right-angle brackets, with elements listed in the order that they must appear. Figure 6 illustrates the presentation of an element named sequence .

Figure 6 Diagram for a sequence

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 choices with the content model (choice1 | choice2 | choice3) .

Figure 7 Diagram for a choice

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 multichoice element has the content model (choice1 | choice2 | choice3)* .



Figure 8 Optional and repeatable set of choices

If an occurrence indicator applies only to a single element, it appears appended to the box with the element name. Figure 9 shows a possibilities element whose content model contains all the occurrence indicators: (seq1, choice1?, choice2+, choice3*) .

Figure 9 All occurrence indicators

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 mixed element may contain both text and elements.

Figure 10 Mixed content model

For Schema resources, if a content model is defined as all , a conforming document must contain exactly one of each element specified in the content model (or zero if an element is specified as optional), with the elements occurring in any order. (Elements within an all content model cannot be repeatable.) Figure 11 illustrates the all content model (all1 & all2 & all3) , represented with an arc.



Figure 11 All content model

Navigating with the Content Model Diagram

The content model diagram also provides navigation to the specifics about a particular element or attribute. To scroll to an element's type definition in the list of elements, right-click on the element while browsing the element in the content model diagram. A context-sensitive menu appears. Click the Go to Element Name option, and the selected element is made active in the list of element definitions.

Editing with the Content Model Diagram

Right-clicking on your content model diagram brings up a menu that allows you to edit your content models. In addition to the navigation features described above, the menu allows you to change the element's occurrence or content.

If you choose to modify the content (content model or data type) for the element, your changes are reflected in the Content and Content Model/Data Type columns of the element/type list below the content model diagram.

Modifying the Display of the Content Model Diagram

To modify the display of the content model panel, right-click the yellow background. A menu appears with the following options.

• Zoom In — zooms in on the diagram.

• Zoom Out — zooms out on the diagram.

• Diagram Attributes — element’s attributes are displayed in the diagram. (This option is selected by default).

• Show Used-by Pane — displays the used-by panel to appear on the right hand side of the content model diagram. This panel displays a list of other elements (if any) that contain the currently selected element in their content model. All potential parent elements that explicitly include this element in their content models are listed. (If no parents appear, then the element may only be used as a document root element or in content models of ANY.) Clicking on any element name in the list makes the element the currently selected element, changing the display.


Schema | 37

SchemaResource

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 TabThe Configuration tab has the following fields.

For a hands-on demonstration of the schema editing environment, see XML Schema Exercises on page 70.

Field Description

Name Name of the file when persisted. The *.xsd suffix will be automatically added.

Target Namespace

Namespace for your declarations and definitions. See Target Namespace Tab on page 38.



Schema Properties PanelDouble-click a Schema resource to edit it. When editing a Schema resource, the configuration panel provides tabs for setting or viewing schema-level properties. You are not required to edit the fields in the configuration panel, although it is recommended that you provide your schema resource with a meaningful name and target namespace.

Target Namespace Tab

The Target Namespace tab has the following fields.

Schema Attributes Tab

The Schema Attributes tab is used to specify schema-level properties (specifically, attributes of the schema element that control how the schema’s components can be used within the schema or within XML instance documents.) Because these attributes serve very specific purposes, the fields within the Attributes tab typically do not need to be edited.

Field Description

Schema Name Name of the file when persisted. The *.xsd suffix will be automatically added.

Target Prefix Prefix used to identify your declarations and definitions as being part of your target namespace. If no prefix is set, the target namespace is also the default namespace for your schema.

Target Namespace

Namespace for your declarations and definitions. A target namespace is provided by default. It is recommended that this namespace be changed to reflect a more meaningful URL.

Import Reserved XML Namespace

Check this field to import the reserved XML namespace, enabling the use of the attributes defined within the XML namespace (xml:lang , xml:space , or xml:base).

Field Description

elementFormDefault By default, the elementFormDefault attribute of the schema element takes the value qualified . Thus, you must declare top-level elements to be associated with a namespace in the instance document.


Schema | 39

Schema Documentation Tab

This tab displays an edit area where you can add schema level documentation for your schema.

attributeFormDefault By default, the attributeFormDefault attribute of the schema element takes the value unqualified . Thus, unless you specify otherwise, only globally declared attributes can be associated with a namespace in the instance document.

blockDefault Use the blockDefault attribute of the schema element to control whether types can be replaced by their derived types in instance documents.

The blockDefault attribute takes one of the values in the drop-down menu. The value you select will prevent type replacement in the instance if derivation is of that value. Select #all to prevent any type replacement by derived types

finalDefault The finalDefault attribute of the schema element allows you to specify that new types may not be derived from any simple or complex type. Click the arrow to display the drop-down menu choices.

id The id attribute on the schema element can be used to apply an identifier value to your schema. The value you give for id must be of type ID , which requires an NCName .

version The version attribute on the schema element can be used to apply a version value to your schema.

Field Description

The settings in the Schema Attributes tab are universal, controlling all of the schema’s components. To specify similar properties for an individual component, use the Properties tab of the properties panel. See Properties Tab, page 58.



Schema Statistics Tab

The Schema Statistics tab is not editable. The tab displays the number of times a schema component type is used. The tab has the following fields.

ToolbarFor a description of the buttons that appear on the toolbar when editing Schema resources, see Toolbar Buttons on page 27.

Schema MenuA 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 PanelThe 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.

Field Description

Element Type Number of element declarations.

Complex Types Number of complex type definitions.

Simple Types Number of user-derived data type definitions.

Attributes Number of attribute declarations

Attribute Groups Number of attribute group definitions.

Model Groups Number of model group definitions.

Notations Number of notation declarations.

Includes Number of includes declarations.

Imports Number of imports declarations.


Schema | 41

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.

Figure 12 Element/Types panel

Elements/Types ListThe 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.

Figure 13 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/ Error Indicator

This column allows you to modify the row and detect errors in the declaration. See Common Columns In Tables on page 26 for more information about this column.

Included Document Indicator

This column indicates whether the declaration comes from a file or from an external schema. See Common Columns In Tables on page 26 for more information about this column.

Warning: Any changes made to unlocked declarations of an included schema will be reflected in the included schema as well.

Declaration Type (D)

Click within this column to indicate whether the row 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.

Element/ Complex Type

This column is labelled as either Element or Complex Type depending on the type of declaration indicated in the Declaration Type column for the selected row. A new element or complex type can be created by clicking on a blank row under the Element/Complex Type column, and then entering a name. To edit an element or complex type name, click on an existing name in the Element/Complex Type name column.

Note: Element and complex type names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.

Derives From The Derives From column allows you to extend or restrict the definition of an existing complex type. Buttons are provided to select the complex type for derivation and to specify whether restriction or extension is desired. Use the Content Model column to specify how the new complex type should be derived from the existing one.


Schema | 43

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.

• Typed — The content is either a simple type (such as xs:string, xs:integer, or xs:float) or a named complex type.

Column Description



Content Model/Data Type

The Content Model/Data Type column displays the 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 Content Model or Data Type , depending on the content type set in the Content column.) 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 45 for more information.

The Insert button provides a drop-down menu that differs depending on whether the content model may include elements or data. The Insert 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-datatypes

Attributes The Attributes column allows the user to specify which attributes may be used for a particular elements. If an attribute name is entered which does not yet exist, it is automatically created with a default data type of xs:string and with no constraints (The declaration can be further refined in the attributes panel at any time. See Attributes Panel on page 50 for more information.)

When the user tabs to an Attributes field, an Insert Attribute button appears. Click the button to access a menu listing previously defined attributes. Selecting an attribute name adds it to the element or complex type being defined

Column Description


Schema | 45

Building Content Models: Occurrence and Sequence Indicators

For element content models, buttons are also provided for applying sequence and occurrence indicators. Table 7 describes the Occurrence indicators. Table 8 describes the Sequence indicators.

Table 7 Occurrence indicators

Occurrence Indicator Meaning In Content Model column,

click...

None The element must appear once and only once. (This is the default occurrence).

? The element (or group of elements) may appear zero or one times. The element is optional, but is only allowed to appear once if used.

Optional but not Repeatable.

+ The element (or group of elements) must appear one or more times. The element is required to appear at least once, but multiple consecutive occurrences may be present.

Repeatable but not Optional.

* The element (or group of elements) may appear zero or more times. The element can appear as many times consecutively as needed, or even zero times.

Repeatable and Optional.

{} The element (or group of elements) must appear within the specified range of times.

{} and specify the min. and max. values for the range.

Table 8 Sequence indicators

Occurrence Indicator Meaning In Content Model

column, click...

| Can be read as 'or'. Creates content model with particles enumerated (only one may be chosen).

Choices

, Can be read as 'followed by,' requiring that the elements or groups of elements appear in the precise sequence indicated.

Sequence

& Elements may appear in any order, but may not be repeatable.

All

() Groups elements, allowing a set of choices or a sequence to be used anywhere that a single element can appear.

()



Occurrence and Sequence indicators combine to make it possible to describe complex structures. For example, a memo might allow multiple entries in its To: and From: fields, multiple (or zero) entries in its cc: field, a single entry for the subject, required content for the body, and an optional set of initials at the bottom for the typist. A MEMO element might therefore have the following content model:

(To+, From+, CC*, Subject, Body, Typist?)

This declaration requires the MEMO element to contain, in sequence, one or more To elements, one or more From elements, zero or more CC elements, a single Subject element, a single Body element, and zero or one Typist elements.

In other cases, a document needs to provide choices. A chapter might require an introduction, but then permit any combination of sections or sidebars. Sequence indicators, in combination with occurrence indicators, can make this possible. The content model for a chapter element might therefore look like:

(Intro, (Section | Sidebar)*)

The Intro 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”.)

Example: Building a Content Model

This section steps you through building a content model for an element or complex type using the buttons provided in the Content Model column. Figure 14 shows a completed content model.

Figure 14 Completed content model

When referencing elements from other namespaces, be sure to prepend the element name with the prefix for the external namespace, followed by a colon (e.g. prefix:componentName). The prefix is listed in the Namespaces tab of the advanced panel. For more information, see Example: Referencing an element from another namespace on page 55.


Schema | 47

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 Title , an Author, multiple Chapters , maybe an Appendix (or several), perhaps a Glossary, and possibly an Index . Assuming these elements are already declared (as shown in the next diagram), the steps to build the content model for Book appear below:

1. In the row for Book , 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 Title). 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.

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 Chapter in the Content Model, and click on the Repeatable button. This adds a '+' indicator after Chapter, to indicate it is repeatable. Likewise, there may be more than one appendix, so highlight Appendix and click Repeatable to add a '+' indicator after Appendix .

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 Glossary, and click the Optional button. Likewise, highlight Index , 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 buttons not used in this example include:

• the Choices button, which indicates choices between several sub-elements (sub-elements are separated by an '|' indicator).

• the All button, which indicates that the elements can appear in any order, but may not be repeatable.

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.


Schema | 49

• The {} button, which is used to set specific occurrence ranges for repeatable elements.

Building Content Models: Content Model Editor

If the space provided by the Content Model column is too small to see all of an element content model, select Expand from the Schema > View menu or press the Ctrl Shift E keys to bring up the Content Model Editor dialog box. The Content Model Editor provides more room for editing, making it easier to work with larger content models, and gives easy access to the elements and reusables. To add an element or reusable model group to a content model, click on its name. Occurrence and Sequence indicator buttons are also available in the editor. The Apply button adds the edited content model to the list, but leaves the editor open. The Cancel button closes the editor without making any changes to the content model in the list, while the Save button closes the editor and makes the changes. Figure 6 illustrates the Content Model Editor.

Figure 15 Content Model Editor

Content Model DiagramThe content model diagram of the elements panel graphically displays the content models in a Schema resource. It presents the relationships between elements (that is, parent elements, child elements, and so on) with diagrams and provides additional information about elements, such as their attributes and occurrence and sequence within a content model. You can use the content model diagram to read, explore, or edit your schemas.

See Content Model Diagram on page 33 for more information about the content model diagram.



Attributes PanelWhen 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 Attributes 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.

Figure 16 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 Selector/Error Indicator



This column indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables on page 26 for more information.

Attribute Name A new attribute can be created by clicking on a blank row under the attribute name column, and then entering a name. To edit an attribute name, click on an existing name in the attribute type name column.

Note: Attribute names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.


Schema | 51

Example: Creating or Editing an Attribute

Attributes are created by declaring an attribute type in the attributes panel or by entering attribute names for an element in the element/type list of the elements/types panel.

Creation of an attribute type within the attributes panel consists of several steps. As an example, let's say we have an element Picture , with the attribute GraphicsType . GraphicsType 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, GraphicsType will be enumerated (that is, it will only ever have the value of JPG , TIF, or GIF). Because the values for this enumeration are best defined as strings, the xs:string data type is

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.

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 of built-in types. An Insert user-defined type button allows you to select from a menu listing the data types (if any) created in the data types panel. See Simple Types Panel on page 66.

Note: For a description of XML Schema’s built-in data types, see http://www.w3.org/TR/xmlschema-2/#built-in-datatypes

Column Description

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 xs:string .



appropriate. An attribute type declaration, by default, sets the data type for an attribute to xs:string . In this example, GraphicsType will be enumerated (that is, it will only ever have the value of JPG , TIF, or GIF). Because the values for this enumeration are best defined as strings, the xs:string data type is appropriate. For example:

2. Right-click the GraphicsType attribute and select Goto Attribute Picture/GraphicsType.

3. Because GraphicsType can be only be a JPG , TIF, or GIF, these values must be entered in the attribute type declaration. Click on the Properties button on the toolbar and then click on the Enumeration tab. In the text box at the top, enter JPG, and then click the Add button. Follow the same procedure to add TIF and GIF.

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


Schema | 53

GraphicsType to JPG , click the Properties tab and enter JPG in the default field.

This completes the declaration for GraphicsType .

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.

Figure 17 Overview panel



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.

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.

Icon XML Schema Component

element

attribute

namespace

complex type

simple type (user-defined data type)

model group

attribute group

XML comment

schema document

included schema


Schema | 55

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.

Example: Referencing an element from another namespace

When building a schema, it is often desirable to reuse components already defined in another schema. If the other schema belongs to a different target namespace, its namespace can be added to (technically, imported into) the schema you are building.

To import a namespace and then reference the components from that namespace, follow these steps:

1. Click the Import button of the overview panel.

Any changes made to unlocked declarations of an included schema will be reflected in the included schema as well.



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 Namespaces 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 address element defined in a different namespace is being used within the content model for a ship-to element.

Figure 18 Referencing an element from another namespace

The prefix used to associate components with the namespace can be changed in the Namespaces tab of the Advanced panel.

An imported schema must belong to a different target namespace than the importing schema. If the external schema shares the same namespace with the schema you are building, consider reusing its components through the Include option described next.


Schema | 57

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.

Example: Including declarations from another schema

When building a schema, it is often desirable to reuse components already declared in another schema. If the other schema belongs to the same target namespace (or no namespace) as the schema you are building, the declarations in the other schema can be added to (technically, included in) the schema you are building.

This example illustrates the steps required to include another schema’s declarations into your schema.

1. Click the Include button of the overview panel.

2. Browse to and select the schema containing the declaration you would like to use. The included module will appear in the Overview tree, identified by the included document icon.

3. The included schema’s declarations will now appear 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.

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 PanelWhen 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 Properties tab, summarized Table 9 below, vary depending on the selected declaration type.

Table 9 Properties tab fields

Field Description

id Use the id field to add an identifier to the selected component declaration.

abstract Check this box to declare the element or type as “abstract”. Abstract elements may not appear in an instance document; rather a member of that element's substitution group must be used in the instance document. If an element's corresponding type definition is abstract, all instances of the element in the XML document must specify a derived type that is not abstract by way of the xsi:type attribute.


Schema | 59

block Use the block property to control whether types can be replaced by their derived types in instance documents. The block property takes one of the following values:

• restriction - prevents type replacement in the instance if derivation is by restriction

• extension - prevents type replacement in the instance if derivations is by extension

• substitution - prevents replacement by substitution groups in the instance document

• restriction extension - prevents type replacement in the instance document if derivation is byrestriction or extension

• restriction substitution - prevents replacement in instance documents by substitution groups and prevents type replacement if derivation is by restriction

• extension substitution - prevents replacement in instance documents by substitution groups and prevents type replacement if derivation is by extension

• #all - to prevent any type replacement in the instance document by derived types or by substitution groups

final The final property allows you to prevent new types from being derived from the selected simple or complex type. The final property takes one of the following values:

• restriction - to prevent derivation by restriction in the schema document

• extension - to prevent derivation by extension in the schema document

• #all - to prevent any derivations at all in the schema document


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.

nillable Click here if you require missing or unknown element content to be stated explicitly in the XML instance document.

substitution group

Use this field to provide an alias for a globally declared element. A reference to the global element validates not just the global element itself, but elements corresponding to any member of the substitution group as well. Elements in a substitution group must have the same type as the global element, or they can have a type that has been derived from the global element's type.

form Use this field to specify whether the selected element or attribute should be either qualified or unqualified in the instance document. If qualified, the element or attribute must be associated with the target namespace in the instance document. If unqualified , a locally declared element or attribute must not be associated with the target namespace in the instance document.

(By default, elements and attributes are defined as unqualified . The default setting can be changed in the Attributes tab of the configuration panel).


Field Description

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.


Schema | 61

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.

length Constrains the value of the type to a single length, as measured by number of characters. (If the base type is hexBinary or base64Binary, this facet constrains the value to a single length, as measured in octets of the binary data.) When specifying this facet, you must use a nonNegativeInteger.

minLength Constrains the value of the type to a minimum length, as measured by numbers of characters. (If the base type is hexBinary or base64Binary, the unit of measurement is octets of binary data.) When specifying this facet, use a nonNegativeInteger.

maxLength Constrains the value of the type to a maximum length, as measured by numbers of characters. (If the base type is hexBinary or base64Binary, the unit of measurement is octets of binary data.) When specifying this facet, use a nonNegativeInteger.



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.

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.

totalDigits Constrains the value of a decimal-based data type to a total number of digits. When specifying this facet, use a nonNegativeInteger.

fractionDigits Constrains the value of a decimal-based data type to a maximum number of digits in the fractional part. When specifying this facet, use a nonNegativeInteger.

pattern Constrains the value of the type to a specific pattern. When specifying this facet, use a regular expression.

maxInclusive Constrains the value of the type to an inclusive upper bound. That is, the type’s value must be less than or equal to this facet’s value.

maxExclusive Constrains the value of the type to an exclusive upper bound. That is, the type’s value must be less than this facet’s value.

minInclusive Constrains the value of the type to an inclusive lower bound. That is, the type’s value must be greater than or equal to this facet’s value.

minExclusive Constrains the value of the type to an exclusive lower bound. That is, the type’s value must be greater than this facet’s value.

Facet Description

When working within the elements/types panel or attributes panel, the constraints applied to a data type exist within the context of the element or attribute declaration only. That is, the constrained data type is not reusable. To create a reusable data type with a given set of constraints, use the data types panel.


Schema | 63

When an enumeration is applicable, the tab can be accessed by clicking the Properties button on the Toolbar, and then clicking the Enumeration tab in the properties panel.

In the text box at the top of the Enumeration tab, enter a value and then click Add. Repeat this procedure for each of the enumeration's values. The values will appear in the list box beneath the text box used for input. You can use the Up and Down buttons to reorder the values in the list. You can also select a value in the list and either Delete it or Replace it with a value entered in the text box at the top. As you edit the enumeration in the Enumeration tab, the current values are reflected in the appropriate column of the active panel.

Advanced PanelWhen 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 Namespaces tab provides an inventory of the external namespaces being used by your schema. The XML Schema 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 Namespaces tab.

The Namespaces 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


Allows you to modify the row and detect errors in the declaration. See Common Columns In Tables on page 26.



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.


Indicates whether the declaration comes from the file 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.

Namespace Corresponds to the target namespace of the imported namespace. This field is populated automatically upon adding a namespace through the overview panel. This field is read-only. If the target namespace for an imported schema changes, the imported namespace should be cleared and re-imported.

Location Corresponds to the relative location of the imported namespace with the project. This field is populated automatically upon adding a namespace through the overview panel. This field is read-only. If the location for an imported schema changes, the imported namespace should be cleared and re-imported.

Column Description

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.


Schema | 65

Figure 19 Notations tab of the advanced pane

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




This column indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables on page 26 for more information about this column.

Name Enter or edit the name of the notation.

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.

Public Name Enter a public identifier for the notation. Public identifiers are not required for notations, though at least one identifier (system or public) must appear. Public identifiers should match the public identifiers standards authors provide for their specifications to ensure uniformity across documents from different sources.

Notation information is processed by the parser only minimally; the applications that process your documents will need to provide an extra level of support to interpret notations.



Simple Types PanelWhen selected from the Schema > View menu or upon clicking the Simple Types button on the toolbar, the simple types panel becomes the primary panel for editing. The simple types panel enables XML Schema authors to create their own simple types (data types), which can then be applied to element declarations and attributes in the schema. These “derived” simple types are created by constraining the set of distinct values available for existing simple types, known as base types. For example, Figure 20 illustrates a user-defined data type called rating that is derived from the base type integer by requiring a minimum value of 1 and a maximum value of 10.

Figure 20 Creating a new simple type

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


Allows you to modify the row and detect errors in the declaration. See Common Columns In Tables on page 26.


Indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables on page 26.

Name A new simple type can be created by clicking on a blank row under the name column, and then entering a name. To edit a simple type name, click on an existing name.

Note: Data type names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.


Schema | 67

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.

Example: Creating a User-Derived Simple Type

In this example a new simple type, called rating is derived. The new type can be any integer from 1 to 10.

1. In the simple types panel, enter the name for the new type.

2. Tab to the Base Type field and use the Native Type button to select the type xs:positiveInteger.

3. Click the Facets button, which loads the Facets tab of the properties panel.

4. In the properties panel, use the minInclusive and maxIncusive facets to restrict the acceptable values of rating to positive integers from 1 to 10.

The rating 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.

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

User-defined types, such as rating , can also be used as base types. To further constrain rating , use the Insert user-defined type button within the Base Type column.

Column Description



Schema Props PanelWhen selected by way of the Schema > View menu, the schema props panel is displayed. For a description of these properties, see Schema Properties Panel on page 38.

Validations PanelWhen 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.

Component Doc PanelThe 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 Schema Documentation tab of the Schema Props panel provides an area where you can add schema level documentation to your schema. The Documentation tab of the Component Doc panel allows you to add component level documentation and document individual declarations and preview their source. When selected by way of the Schema > View menu, the Component Doc panel appears between the active editing panel and the configuration panel.

The name for your schema can only be specified in the configuration panel.

A red selector button in a declaration panel is indicative of an 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.


Schema | 69

When the Component Doc panel reflects the selected declaration, the following tabs are available:

Source PanelWhen 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.

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.

XML Schema uses two elements for annotations: documentation and appinfo . The Documentation tab displays and adds documention annotations only, which are intended to facilitate human understanding of the schema. There is no facility for adding appinfo annotations through the Component Doc panel.



XML Schema Exercises

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.

Exercise 1: Building a Simple SchemaIn this example, you will build an XML Schema 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

manufacturer a container for information about a manufacturer

name the name of the manufacturer

date.issued the date the price list was issued

product a container for information about a product

sku the product's sku (Stock Keeping Unit - Inventory Identifier)

product.name the product's name

price the product's price

description a text description of the product

promotion a container for information about a price promotion

start.date the date the promotion starts

end.date the date the promotion ends


XML Schema Exercises | 71

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 root and replace it with manufacturer.

b. Tab across to the Attributes column and type in name . Here you can define attributes for an element. When entering multiple attributes, commas should separate them.

6. To create the next element, move your cursor to the row below manufacturer and type date.issued .

You can navigate around the tables in each panel by using ENTER, TAB, SHIFT-ENTER, and SHIFT-TAB.



7. Now define date.issued as a date using the following steps:

a. Tab to the Content column.

b. Click the Content Type button and select “Type” from the drop down menu.

c. Tab to the next field. (Notice that the column heading changes from “Content Model” to “Data Type”.) To provide the date.issued element with an appropriate data type, select date from the menu that appears upon clicking Insert.

8. To specify that the manufacturer element must always include the date.issued element

a. Move to the Content column on the manufacturer row

b. Select “Elements” from the Content Type menu. This restricts the content model for manufacturer to elements only.

c. Tab to the Content Model column and click the insert button.

d. Select date.issued to restrict the contents of manufacturer to one and only one date.issued element.

You are now ready to create a second element called product.

1. Move to the empty line below date.issued and type product . Press tab. Select “Elements” from the Content Type menu and press tab.

2. Move to the Content Model column for product , position your cursor inside the “()” and type sku, product.name, price, description, promotion .

The commas between elements indicate 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 sequences. (For more information on sequence indicators see Building Content Models: Occurrence and Sequence Indicators on page 45).



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 description an optional element:

a. Go back to the product content model and highlight description.

b. Once highlighted, click the “optional” button on the tool bar that appears. Notice the '?' that was appended to description.

5. Make price a decimal data type by clicking on price where it appears in the Element column. Tab over to the Content column and select “Type” from Content Type drop down menu. Tab over to the Data Type column and choose decimal from the Insert menu.

6. 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 promotion by specifying “Elements” in the Content column and then entering price into the Content Model column.

7. Tab to the Attributes column for promotion and enter start.date, end.date . Press Tab.

To further refine the definitions of these attributes, you can right-click on each of their names and choose “Go to <name>“or click Attributes on the toolbar.

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.

For more information on occurrence indicators, see Building Content Models: Occurrence and Sequence Indicators on page 45.



The attributes panel will appear with options for data typing the attribute and for indicating its usage (optional, required, default, fixed, or prohibited).

8. Within the attributes panel, indicate that the values of the start.date and end.date attributes should be of type date .

XML schemas typically have a single root element that contains all other elements. In this schema, our root element will be called price.list .

1. Return to the elements/types panel and add an element named price.list . Press tab and specify “Elements” content.

2. Enter manufacturer, product+ as the content model. (The plus sign designates the productelement as required and repeatable.) Tab out of the field to update the schema.

Congratulations! You have completed creating the schema. In the configuration panel, name the file “pricelist”. You may also want to change the automatically generated target namespace to a URL meaningful to your organization.

Click Apply to save your work.

You can use the navigation buttons on the toolbar or the Schema>View menu to open and close between the editor's panels.

The Apply button makes the file available to other resources in the project. The schema is saved when the entire project has been saved.



Reviewing the Schema

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 price.list , will produce a graphical view of the entire schema.

The diagram for the price list schema is shown in Figure 21.

Figure 21 Graphical view of the schema

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.

Element ContentIndicator



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.

Exercise 2: Defining and Deriving Complex and Simple TypesIn this example, you will build a sample XML Schema for an address. The exercise introduces a modular approach to schema design, as more detailed complex and simple types are derived from more generic ones. Here is a guide to the information you'll be using.


Address Complex type from which two other complex types are derived

name Element for the name of the addressee

street Element for the street address

city Element for the city

USAdress Complex type derived by extension from Address

state Element for the state

zip Element for the zip code

UKAddress Complex type derived by extension from Address



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 Address 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 Address 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.)

postcode Element for the UK postal code

exportCode Element for the UK export code

USState Simple type containing an enumeration




7. Tab to the Content Model field. With the pointer positioned between the parentheses, type in the following elements, separated by commas: name, street, city.

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.

Continue building the address schema by defining a simple type named USState .

1. In the Toolbar, click the Data Types button.

2. In the first field in the Name column, type USState . Tab to the Base Type column. Click Type and choose string from the drop-down menu.

3. Tab to the Options column. To define a list of possible values for USState , click the Edit Enums button. The properties panel appears in the lower left of the application window with the Enumeration tab active. In the text box at the top of this tab, enter the value 'AK' (without quotes) and then click Add.




Follow the same procedure for the values 'AL' and 'AR'. (Of course, there are more postal abbreviations, but let’s stop here.)

4. The enumeration is automatically created in the Options column of the data types panel.

Now you can define a complex type named “USAddress”.

1. On the toolbar, click Elements/Types to return to the elements/types panel (you may also need to choose Schema > View > Properties to clear properties.)

2. Make sure the bottom row of the element/type list reflects a complex type declaration. (A “T” should appear under the column “D”).

3. In the adjacent empty field, type USAddress .

4. Tab to the Derives From column and click Extends. Next, click Select and select Address . Notice that the column heading changes to “Extends”.

Notice also that your selection is inserted in the column with the prefix “e_”. This indicates that the type USAddress is being derived from the base type Address by extension. If you derive from a base type by restriction, you'll see the prefix “r_”.



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 state, zip . Tab out of the Content Model column.

7. In the Auto-Create dialog box that appears, click the Globally defined radio button and then click Create.

8. In the row for the element state , navigate to the Data Type column. Click Insert user-defined type and select USState from the menu of options.

9. In the row for the element zip , 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 positiveInteger as the data type for zip .

You are now ready to define some elements on your own.

1. Define a complex type named UKAddress as an extension of Address . Add the element postcode to the content model and create postcode as a global declaration. Also give UKAddress and attribute called exportCode.

2. For further practice, define a simple type (data type) called UKPostcode and assign it to the postcode 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, shipTo and billTo elements could be added to this schema and be declared as having the type USAddress . 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 shipTo of



type USAddress . To references an element, attribute or type existing in another namespace, use the prefix for the external namespace followed by a colon and the component name. Figure 22 shows a new schema referencing the USAddress type created in this schema.

Figure 22 Referencing a complex type in another schema

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.



DTDResource

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

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.

For a hands-on demonstration of the editing environment, see DTD Exercise on page 113.

Field Description

Name This is the name of the file when persisted. The *.dtd suffix will be automatically added.

Field Description

Elements The number of element declarations is displayed.


DTD | 83

ToolbarFor a description of the buttons that appear on the toolbar when editing DTD resources, see Toolbar Buttons on page 27.

Schema MenuA 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.

Complex Types The number of complex type definitions is displayed. (This is an XML Schema metric only.)

Attributes The number of attribute declarations is displayed.

Attribute Groups The number of attribute group definitions is displayed.

Model Groups The number of model group definitions is displayed.

Data Types The number of user-derived datatype definitions is displayed. (This is an XML Schema metric only).

Namespaces The number of namespace declarations is displayed. (This is an XML Schema metric only.)

Included Modules The number of included modules is displayed.

Notations The number of notation declarations is displayed.

Processing Instructions The number of processing instructions is displayed.

Field Description



Elements PanelThe 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).

The Element ListThe element list, located at the bottom of the elements panel, is where much of the creation and editing of element declarations takes place. Each element 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





Warning: Any changes made to unlocked declarations of an external parameter entity will be reflected in the external schema as well.

Element Name

A new element can be created by clicking on a blank row under the Element column, and then entering a name. To edit an element name, click on an existing name in the Element column

Note: Element names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.


DTD | 85

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 integer or date -- are not afforded by DTDs. Accordingly, selecting the Type option is equivalent to selecting the Text option.

Column Description



Content Model

The Content Model column displays the content model of the 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.

Attributes The Attributes column allows the user to specify which attributes may be used for a particular element. If an attribute name is entered which does not yet exist, it is automatically created with a default data type of string and with no constraints. (The declaration can be edited in the attributes panel at any time.)

When the user tabs to an Attributes column, an Insert Attribute button appears. Click the button to access a menu listing previously defined attributes and reusable attribute groups. Selecting an attribute name or a reusable adds it to the element or complex type being defined.

Column Description


DTD | 87

Building Content Models: Occurrence and Sequence Indicators

For element content models, buttons are provided for applying sequence and occurrence indicators. Table 10 describes the Occurrence indicators. Table 11 describes the Sequence indicators.

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.



column, click...

None The element must appear once and only once.

(This is the default occurrence).


Optional but not Repeatable


Repeatable but not Optional.


Repeatable and Optional.



column, click...


Choices



Occurrence and Sequence indicators combine to make it possible to describe complex structures. For example, a memo might allow multiple entries in its To: and From: fields, multiple (or zero) entries in its Cc: field, a single entry for the subject, required content for the body, and an optional set of initials at the bottom for the typist. A MEMO element might therefore have the following content model:

(To+, From+, Cc*, Subject, Body, Typist?)

This declaration requires the MEMO element to contain, in sequence, one or more To elements, one or more From elements, zero or more Cc elements, a single Subject element, a single Body element, and zero or one Typist elements.

In other cases, a document needs to provide choices. A chapter might require an introduction, but then permit any combination of sections or sidebars. Sequence indicators, in combination with occurrence indicators, can make this possible. The content model for a chapter element might therefore look like this:

(Intro, (Section | Sidebar)*)

The Intro 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”.)

Example: Building a Content Model

This section steps you through building a content model using the buttons provided in the Content Model column. Figure 23 shows a completed content model.

, Can be read as 'followed by,' requiring that the elements or groups of elements appear in the precise sequence indicated

Sequence


()



column, click...


DTD | 89

Figure 23 A completed content model for a Book element

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 Title , an Author, multiple Chapters , maybe an Appendix (or several), perhaps a Glossary, and possibly an Index . Assuming these elements are already declared, the steps to build the content model for Book appear below:

1. In the row for Book , 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 Title). 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.

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 Chapter in the Content Model, and click on the Repeatable button. This adds a '+' indicator after Chapter, to indicate it is repeatable. Likewise, there may be more than one appendix, so highlight Appendix and click Repeatable to add a '+' indicator after Appendix .

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 Glossary, and click the Optional button. Likewise, highlight Index , 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.

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.

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


DTD | 91

Building Content Models: Content Model Editor

If the space provided by the Content Model column is too small to see all of an element content model, select Expand from the Schema > View menu or press the Ctrl-E keys to bring up the Content Model Editor dialog box. The Content Model Editor provides more room for editing, making it easier to work with larger content models, and gives easy access to the elements and reusables (internal parameter entities). To add an element or reusable to a content model, click on its name. Occurrence and Sequence indicator buttons are also available in the editor. The Apply button adds the edited content model to the list, but leaves the editor open. The Cancel button closes the editor without making any changes to the content model in the list, while the Save button closes the editor and makes the changes. The Content Model Editor is shown in Figure 24 on page 91.

Figure 24 Content model editor

Building Content Models with Reusables (Internal Parameter Entities)

While breaking schemas into modules is helpful in large-scale situations where entire sets of declarations are shared within schemas, there are many cases where smaller chunks of declarations can be usefully shared and centrally managed. The reusables (internal parameter entities) editors allow you to define pieces of declarations, which you can then reuse as appropriate. If you later need to make changes to that content, you just change the reusable, and all of the declarations using that reusable will be updated automatically.



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.

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.

Figure 25 Referencing a reusable (internal parameter entity)

To edit or delete an existing group definition, select the Edit Reusables option of the Schema menu (Schema > Tools > Edit Reusable).

Resuable Editor Description

Model Group Use this editor to create model group reusables (parameter entities), which store content models that can be included in element content models. These reusables can provide the entire content model or be included as part of a larger content model. Model Group reusables must contain acceptable element content models.

Attribute Group Use this editor to create a group of attribute declarations (as a parameter entity), allowing the same group of attributes to be applied to multiple elements. Attribute Group reusables must contain sets of attribute names, separated by commas.

Constraints Use this editor used to express the limitations placed on attributes with enumerated values. Constraints reusables (parameter entities) must list acceptable values separated by vertical bars.

Text Use this editor to create reusable text (parameter entity).

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.


DTD | 93

The Content Model Diagram The content model diagram of the types panel graphically displays the content models in a DTD resource. It presents the relationships between elements (that is, parent elements, child elements, and so on) with diagrams and provides additional information about elements, such as their attributes and occurrence and sequence within a content model. You can use the content model diagram to read, explore, or edit your schemas.

See Content Model Diagram on page 33 for more information about the content model diagram.

Attributes PanelWhen 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.

Figure 26 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





Attribute Name A new attribute can be created by clicking on a blank row under the attribute name column, and then entering a name. To edit an attribute type name, click on an existing name in the attribute type name column.

Note: Attribute names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.

Element The Element column references 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. If the same attribute needs to be assigned to multiple elements, those assignments should be made in the Attributes column of the Element List area of the elements panel.

If an attribute is used by multiple elements, it will be listed in the attributes panel as shared. To bring up a list of the multiple elements using a particular attribute, right-click on the word 'shared'. To separate the definition for a particular element (to choose a different default value, for instance), select the name of the element from the pop-up menu. A separate entry for that attribute will be created. To avoid separating the definitions, click outside of the pop-up menu.


DTD | 95

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.

Constraints The Constraints column allows you to limit the choices available for attribute values. This column is only applicable if the enumerated type is selected in the Data Types column. In this case, the Edit Enums button loads the enumerations editor (the Enumerations tab of the properties panel), where you can specify a list of possible values (of the specified data type) for the attribute. For more information on constraining attribute values, see Properties Panel on page 102.

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 default or fixed , enter the default or fixed value in the Value column. Choosing either optional or required and then entering a value in the Value column will produce an error message. Choosing either default or fixed and omitting a value in the Default column will also produce an error.

Column Description


DTD | 97

Table 12 Datatypes within a DTD

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.

IDREF The attribute value must match the value of an ID attribute of an element contained within the same XML document.

IDREFS Multiple values of ID attributes may appear, separated by white space, but all must match ID values in the document. (A single ID value is also acceptable.)

ENTITY The attribute value must match the name of an external unparsed entity declared elsewhere in the document type definition. (Colons are prohibited within the value of this type of attribute for documents conforming to the Namespaces recommendation.)

ENTITIES Like ENTITY, except that multiple names of unparsed entities 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.)

NMTOKEN The attribute value must contain letters, digits, periods, dashes, underscores, combining characters or extenders. No other characters (including white space) may appear. (Colons are prohibited within the value of this type of attribute for documents conforming to the Namespaces recommendation.)



Example: Creating or Editing an Attribute

Attributes are created by declaring an attribute type in the attributes panel or by entering attribute names for an element in the element list of the elements panel.

Creation of an attribute type within the attributes panel consists of several steps. For example, assume you have an element Picture , with the attributes GraphicsType . GraphicsType is an attribute that tells us if a picture is a JPG, TIF, or GIF file. Here are steps for declaring GraphicsType :

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

enumerated Provides a list of acceptable values. The word enumerated isn't stated in the declaration. Instead, a list of possible values for the attribute appear in the Constraints area in parentheses, separated by vertical ('or') bars. (value | value).

NOTATION The NOTATION keyword must be followed by a list of acceptable notation identifiers in the same format - (value | value...) - used for enumerated values. All values provided must have been declared as NOTATIONS elsewhere in the document type definition.

Table 12 Datatypes within a DTD

Datatype Meaning

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


DTD | 99

1. Click on a blank line under the Attributes Name column. Enter the attribute name GraphicsType . 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 GraphicsType . Since we know this attribute will be used by the element Picture , type in Picture .

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 string . In this example, GraphicsType will be enumerated (that is, it will only ever have the value of JPG , TIF, or GIF).

4. Click the Type button and select enumeration from the XML Types menu.

Since GraphicsType can be only be a JPG , TIF, or GIF, 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 GraphicsType to JPG , 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 GraphicsType .

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.

Figure 27 Overview panel


DTD | 101

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.

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

Icon XML Schema Component

element

attribute

model group (internal parameter entity)

attribute group (internal parameter entity)

XML comment

schema document

included schema (external parameter entity)

Any changes made to unlocked declarations of an included schema will be reflected in the included schema as well.



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.

Example: Including declarations from another schema

When building a schema, it is often desirable to reuse components already declared in another schema.This example illustrates the steps required to include another schema’s declarations in your schema.

1. Click the Add Module button of the overview panel.

2. Browse to and select the schema containing the declaration you would like to use. The included module will appear in the Overview tree, identified by the included document icon.

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 PanelWhen 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 enumeration , use the Enumeration tab to create a list of possible values.

Modules can also be added using the Parameter Entities tab of the advanced panel.


DTD | 103

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 enumeration . The Enumeration tab is shown in Figure 28.

Figure 28 Enumerations tab of the properties pane

When an enumeration is applicable, the tab can be accessed by:

• clicking the Properties button on the Toolbar, and then clicking the Enumeration tab in the properties panel.

• clicking the Edit Enums button in the Data Types column of the attributes panel

In the text box at the top of the Enumeration tab, enter a value and then click Add. Repeat this procedure for each of the possible values. The values will appear in the list box beneath the text box used for input. You can use the Up and Down buttons to reorder the values in the list. You can also select a value in the list and either Delete it or Replace it with a value entered in the text box at the top. As you edit the enumeration in the Enumeration tab, the current values are reflected in the Constraints column of the attributes panel.

Advanced PanelWhen 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.



Parameter Entities Tab

When working with a DTD resource, the Parameter Entities tab provides access to internal and external parameter entities definitions. Internal parameter entities are used to implement reusable declarations or text (Schema > Tools > Define Reusable), while external parameter entities are used to support the modular schema architectures provided by the overview panel’s Add Module feature. Users familiar with DTD syntax may prefer to add parameter entities directly through the Parameter Entities tab.

The parameter entities tab is divided into two panels. The top panel is used for internal parameter entities, whose values contain their replacement content directly, while the bottom panel is used for external parameter entities, which contain references to external files that contain content.

Internal parameter entities have only a name and a value. (Entity names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods.) The value must contain either complete declarations (more common in external entities) or fragments of single declarations. Declarations may not cross entity boundaries, though they may contain multiple entities. Entities may also contain entities themselves.

For example, to create an entity named 'shortened' that has the value '(title, paragraph)' - an element content model - the entries shown in Figure 29 would be appropriate.

Figure 29 Creating an internal parameter entity

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;

Figure 30 illustrates the use of a parameter entity within a content model.

Figure 30 Referencing a parameter entity within a content model


DTD | 105

External parameter entities have names and references to external resources. External parameter entities must have system identifiers (either a full or relative path name to another DTD in your project) and may optionally have public identifiers as well. An 'Include in DTD' check box is provided that makes it easy to include external modules in your DTDs. If the external DTD contains multiple declarations, you'll want to make sure it gets checked.

Modules that have been added through the overview panel will appear here, and modules added here will appear in the overview panel. When you add a module, its content is downloaded for use in the current schema. The parameter entity declarations for that module will also appear in the parameter entity window, preceded by an icon if the module hasn't been opened for editing in the overview panel. A listing of external parameter entities is shown in Figure 31.

Figure 31 Listing of external parameter entities

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.

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.



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

Internal General Entities

Defining an internal general entity requires only the entry of a name and a value. The value must be plain text or well-formed XML - all start tags in the entity must have end tags and vice versa. Figure 32 illustrates the creation of two internal general entities.

Figure 32 Defining internal general entities

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 &productName; (&productNum;) is the finest of its breed.

will become:

Our new Capital 8850 (CXY-8850) is the finest of its breed.

External General Entities

External general entities work very similarly, except that the value isn't given in the declaration. Instead, a reference to another document in your project is provided (either a full or relative path name), and the contents of the referenced document are used as the value for substitution. Like the value of an internal


DTD | 107

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.

Figure 33 Defining an external general entity

External general entities are referenced from documents the same way that internal general entities are referenced -- using the &entityName; syntax. In this case, &play; would reference the XML document 'othello.xml' and include it in a document.

External Unparsed Entities

The last kind of entity that can be created in the general entities tab is the unparsed external entities. Unparsed entities reference non-XML content, like graphics files or data. Documents reference unparsed entities through the use of attributes of type ENTITY or ENTITIES. To create an unparsed entity, provide the same information as would be provided for an external general entity (name, system identifier, optional public identifier), but also provide a notation in the Notation column to identify the file type that is being referenced. This notation must be declared on the Notations tab. The 'myGraphic' unparsed entity shown below in Figure 34 is an example of an unparsed entity.

Figure 34 Defining an external unparsed entity

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





Name Enter or edit the name of the notation.


DTD | 109

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

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.

Public Name Enter a public identifier for the notation. Public identifiers are not required for notations, though at least one identifier (system or public) must appear. Public identifiers should match the public identifiers standards authors provide for their specifications to ensure uniformity across documents from different sources.

Column Description

Notation information is processed by the parser only minimally; the applications that process your documents will need to provide an extra level of support to interpret notations.

Column Description







Schema Properties PanelWhen selected by way of the Schema > View menu, the schema properties panel is displayed. The schema properties panel provides a count of the different type of components used to build the DTD. (This information is also found on the Statistics tab of the configuration panel).

Errors PanelWhen 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.

Notes PanelThe 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.

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,

Column Description

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.

A red selector button in a declaration panel is indicative of an error.


DTD | 111

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:

When the notes panel reflects the document as a whole, two 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:



Source Preview Displays the source code for the selected declaration.

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 PanelWhen 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 | 113

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:

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.


price.list the “root” element inside of which all others will appear

manufacturer a container for information about a manufacturer

name the name of the manufacturer

date.issued the date the price list was issued

product a container for information about a product

sku the product's sku (Stock Keeping Unit - Inventory Identifier)

product.name the product's name

price the product's price

description a text description of the product

promotion a container for information about a price promotion

start.date the date the promotion starts

end.date the date the promotion ends



3. Within the design panel, double click the DTD icon.

4. A new set of panels will appear. Resize the panels, such that the elements panel is prominently displayed. The elements panel presents an inventory of all of the elements and complex types allowed within a document conforming to this schema. The elements panel consists of the content model diagram (upper half) and the element list (lower half). The element 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.

Now you are ready to build the schema.

5. In the Element column, select root and replace it with manufacturer.

6. Tab across to the Attributes column and type in name . Here you can define attributes for an element. When entering multiple attributes, commas should separate them.

7. To create the next element, move your cursor to the row below manufacturer and type date.issued . 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 manufacturer to ensure that the manufacturer element always includes the date.issued element.

8. Move to the Content column on the manufacturer row and select “Elements” from the Content Type menu. This restricts the content model for manufacturer 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.

You can navigate around the tables in each panel by using ENTER, TAB, SHIFT-ENTER, and SHIFT-TAB.


DTD Exercise | 115

10. Type date.issued into the Content Model column to restrict the contents of manufacturer to one and only one date.issued element. Since name is an attribute, it does not need to be within the manufacturer element.

11. Move to the empty line below date.issued and type product then press tab. Select “Elements” from the Content Type menu and press tab.

12. Move to the content model column for product , position your cursor inside the “()” and type sku, product.name, price, description, promotion

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

.

As it is currently defined, all elements are required. In some instances, you may want an element to be optional. For the purposes of this exercise, description will be made an optional element.

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.



14. Go back to the product content model and highlight description . Once highlighted, click the “optional” button on the tool bar that appears. Notice the '?' that was appended to description .

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 promotion by specifying “Elements” in the Content column and then entering price into the Content Model column.

16. Tab to the Attributes column for promotion and enter start.date, end.date . 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 price.list . Below promotion , type in price.list , press tab, and specify “Elements” content.

18. Enter manufacturer, product+ as the content model. (The plus sign designates the product element as required and repeatable.) Tab out of the field to update the schema.

Congratulations! You have completed creating the schema. In the configuration panel, name the file “pricelist” and click Apply to save your work.

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.



DTD Exercise | 117

Reviewing the Schema

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 price.list , will produce a graphical view of the entire schema, shown in Figure 36.

Figure 36 Graphical view of the schema

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 integer, decimal and date 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 | 119

InstanceResource

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.

Figure 37 XML instance editing environment

For a hands-on demonstration of the instance editing environment, see the XML Instance Exercise on page 137.



Configuration PanelWhen editing an Instance resource, the Configuration tab has the following fields:.

ToolbarFor a description of the buttons that appear on the toolbar when editing Instance resources, see Toolbar Buttons on page 27.

XML MenuAn 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 SchemaThe 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.

Field Description

Name This is the name of the file when persisted. The *.xml suffix will be automatically added.


Instance | 121

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.

Content PanelThe 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.

Figure 38 Content panel

Right-click the Set Schema button to choose from a list of recently applied schemas.

TagArea

EditArea

ContentHints

FactoryBar



Content Panel: Tag AreaThe tag area appears as a shaded column to the left of the edit area in the main window. It displays all of the component that comprise the instance document. Blue icons are used to distinguish the components, as described in the table below.

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

Inserting new elements, attributes, processing instructions, and comments

Graphical document building tools are provided that facilitate the insertion of new elements, attributes, processing instructions, comments, and text. The two main insertion tools are the Insert box, which appears in the tag area, and the factory bar which appears in between the Tag and Edit areas and the errors panel.

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

Icon Component

Element

Attribute

Comment

Processing Instruction

Text


Instance | 123

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, street and city are siblings to the selected element, street , and hence, appear along the same vertical line. The elements shipTo and item appear to the left of the selected item, indicating parent and grand-parent relationships, respectively.

Figure 39 Insert box

In Figure 39, a name (suiteNumber) for a new sibling element for street has been entered into the text box. With a single click on the appropriate icon, this new entry can be changed from an element into an attribute, text, comment, or processing instruction. When you are finished entering and defining your new tags, either hit tab or enter to complete the entry.

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.

Figure 40 Factory bar

insert as sibling

insert as parent

insert as child



insert new comment

insert new text


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.



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.

Figure 41 Inserting a comment

Modifying Document Structure

A right button menu, shown in Figure 42, provides the basic cut, copy, paste, clear and rename functions to enable you to make changes to the elements and attributes within the tag area. (For an explanation of the other options on this menu, see Creating a Customized View of the Tag Area on page 126.)

Figure 42 Right button menu


Instance | 125

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.

Identifying Data-Entry Constraints

When creating an XML document based on a schema, the tag area facilitates data entry into the edit area by providing a guide to the type of data that is required by the schema. When you mouse over the element and attribute tags appearing in the tag area, a tool tip is created which describes the type of data that should be entered in the edit area. For example, in Figure 43, the tool tip indicates that the content for the quantity element should be entered as an int (integer) to conform to the schema.

Figure 43 Content hint as tool tip

Navigating the Document

The navigator bar appears along the top of the content panel (below) tracks your movements throughout the tag area, displaying your selected element or attribute along with each of its element antecedents, all the way up to the document root. Notice in Figure 44 that the entire ancestry of the element selected in the tag area--street--is illustrated on the navigator bar.

Figure 44 Navigator bar

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 billTo element.



Figure 45 Siblings displayed on navigator bar

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.

Creating a Customized View of the Tag Area

The tag area can be customized in numerous ways to facilitate data entry and to make the presentation of the document more intuitive and user-friendly. Customized views are preserved and associated with the schema used to create this document. This means that, as long as needed, every new XML document created using the same schema will be presented the same way automatically.

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 address elements, the menu choice will only affect the address 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.

Your customized view can be saved by way of the Presentation menu (XML>Presentation). Multiple presentations may be associated with a given schema, providing multiple display options for an instance document.


Instance | 127

Figure 46 Item and type level (right-button) menus

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



Expanding and collapsing elements

To allow for a cleaner view of your document at a particular level of its hierarchy, you can expand or collapse sections of the tag structure by clicking the small + or - icons preceding element tags. All elements of a particular type (e.g. all address elements) can be collapsed at once by right-clicking on an instance of element in the tag area and selecting the “Element Type” option from the drop down menu. A second menu will appear with the expand and collapse options.

Hiding elements and attributes

If you are working with a specific set of elements in a document, you may want to hide the elements and attributes you are not editing. Elements and attributes can be hidden either on an item basis (hide only one instance) by right-clicking on the element and selecting hide from the initial drop-down menu. Elements and attributes can be hidden on a type basis (hide all instances) by right-clicking on the element and selecting “Element Type” from the first drop down menu and “Hide” from the “Element Type” sub menu.

To show elements that have been hidden, select the parent of the hidden element and use the “Show” or “Show All” functions accessible through the item and type-level drop down menus. The Show command is used to select an individual element or element to be shown, as shown in Figure 47, while “Show All” displays all elements or elements previously hidden within the selected element.

Figure 47 Selecting a hidden element to show

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.


Instance | 129

Creating aliases for elements and attributes

Element or attribute names that are not easily understood can be given an alias in your view of the document. The alias is only designed to help users understand the meaning of a tag within the tag area without having to rename the element. Aliases will not appear in the source panel and the original element names will be preserved when the document is saved.

An alias can only be applied at the type level (meaning all instances of the selected element or attribute name will be displayed with the alias name), using the Alias option of the type level submenu of the right button menu. A dialog box will appear where you can set the alias. In Figure 48, the attribute dur is given the alias of duration .

Figure 48 Specifying an alias

Adding color to your tags

Color highlighting can be applied to make the instance document more intuitive and to showcase important areas. Color can only be applied at the type level (meaning all instances of the selected element or attribute name will be highlighted with the selected color), using the Color option of the type level submenu of the right button menu. Six colors are available, as shown in Figure 49.

Figure 49 Color options



Once a color has been selected, the tag’s default background color (light gray) will change to the chosen color.

Promoting elements and attributes

You can customize your view from the default vertical format to a horizontal tabular format by promoting one or more attributes or (child) elements to the same line as the parent. This helps isolate a selected element or attribute type for data entry. Promotion also provides a more concentrated view of the document, especially useful for documents with many elements and attributes holding small amounts of text.

Promotion is performed at the type level only (meaning all instances of the selected element or attribute will be promoted), using the Promote option of the type level submenu of the right button menu.

Figure 50 illustrates the tabular format created through promotion. In this example, the attributes name and focus have been placed on the same row as their element, sale_agent and the elements total_sales , total_calls , nails , and screws have been placed on the same row of their parent, monthly.

Figure 50 Promoted elements and attributes

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 monthly has been resized to allow for three lines of promotion.

Promotion can also be performed by dragging and dropping an attribute or child element from the tag structure into the edit area on the same row of the parent element.


Instance | 131

Figure 51 Resizing rows to allow for additional promotion

To cancel a promotion, right click the promoted item and choose Demote from the menu.

Content Panel: Edit AreaThe edit area, adjacent to the tag area in the content panel, is where the data associated with the elements and attributes that appear in the tag area is entered.

While entering data in the edit area is very straight forward -- much like filling out a form -- the following tips will help you add to your document with greater ease.

When building documents based on a schema:

• a single mouse click activates the data entry field for elements defined as text only.

• mixed content models default to the “show as markup” view; all other content models default to “show as rows”. See “Show as Rows” versus “Show as Markup” on page 134 for more information.

• data should be entered directly over the content tips, which appear as grayed-out text strings and describe the expected content for the element or attribute.

• when data entry in a particular field is complete, press Enter or Tab to move to the next field.

When building documents with no schema:

• when a new element is added, the data entry field is initially activated with a double click, after which only a single click is required.

• when data entry in a particular field is complete, press Enter or Tab to move to the next field.

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.

Figure 52 Content hints

Content ModelAttribute Value Data Type

Data Type (with dropdown menu of available choices)

Attribute Default Value


Instance | 133

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 Indicator Meaning

None The element must appear once and only once.




{} The element (or group of elements) must appear within the specified range of times.


Occurrence Indicator Meaning


, Can be read as 'followed by,' requiring that the elements or groups of elements appear in the precise sequence indicated

& 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.)

Content hints are displayed by default. They can be turned off by way of the XML menu (XML > View > Content Hints).

“Show as Rows” versus “Show as Markup”

Element and attribute content can be displayed in either a row format or in markup format. When a element's content is displayed in row format the element, along with each of its child elements, appear in the tag area along with a corresponding data entry field in the edit area. Figure 53 shows a date element in row format.

Figure 53 Row format (the default view)

When an element's content is displayed as markup, all of the element's content (that is character data, child elements, child element character data, and so on) is displayed as XML in the edit area. Figure 54 shows the date element in markup format.

Figure 54 Markup format

A row holding content shown as markup can be collapsed or expanded by way of the blue icon appearing at the end of the data entry field. In Figure 55, the field has been expanded to show all of the markup content associated with the element Date .

For a description of the data types that may appear as content hints, see http://www.w3.org/TR/xmlschema-2/#built-in-datatypes


Instance | 135

Figure 55 Blue ellipsis icon for collapsing or expanding markup view

Errors PanelWhen 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.

By default, data is presented in “show as rows” formatting. The two exceptions are mixed content models and comments, which are displayed as markup by default.

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 PanelWhen 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).


XML Instance Exercise | 137

XML Instance Exercise

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.

When working with Instance resources, TIBCO Designer operates as a “schema-aware” editor, which means you can validate your XML documents against a DTD or XML Schema as you build them or after they have been created. In our example, we will create an XML document using the price list schema created in the first XML Schema Exercise (see XML Schema Exercises on page 70) as a template. The example will also demonstrate the customizable view you can create of the XML document as well as all documents you later create based on the same schema.

Getting Started1. 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 price.list 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

This exercise requires the use of the price list schema created in the first XML Schema exercise.



area. Additionally, the structure of the document as defined by the schema is visible as content hints viewable in the edit area. The tag and edit areas comprise the content panel, which is shown in Figure 56.

Figure 56 Content panel

Building Your DocumentThe factory bar, illustrated in Figure 56 above, is one way you can insert additional elements or attributes into your document; you can also double-click on an element within the tag area and use the drop-down window that appears to add components to your document. Figure 57 depicts the document-building options.

Edit area

Content hints

Tag area

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.



Figure 57 Document-building options

1. To add the name attribute to the manufacturer element, click on manufacturer within the tag area. Once manufacturer is selected, name becomes an option on the factory bar. Click once on name to add it to the document.

2. Select promotion within the tag area, and use the factory bar to add the start.date and end.date attributes.

S

Customizing and Populating Your DocumentNow we will customize the view we have of this document to make it more approachable and facilitate the entry of data within it. The view we create will be preserved and associated with the schema used to create this document. This means that as long as needed, every new XML document created using the same schema will be presented the same way automatically. (Multiple presentations may be associated with a given schema, providing multiple display options for an instance document.)

insert as sibling

insert as parent

insert as child



insert new comment

insert new text




1. If you right-click on the element manufacturer, a menu of options will appear. Select Element “manufacturer” > Color > Green to highlight the element with a green background.

You will notice that the manufacturer element has now been highlighted in green. This makes finding the element to add data or content easy and identifies each occurrence of the element.

2. Use the same procedure to highlight the product element in yellow and the promotion element in blue.

S

3. Now you can promote the child elements as well as the attributes of manufacturer 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 manufacturer.

4. Now drag the element date.issued up to the right of the attribute name , on the same level of manufacturer.

5. Promote sku , product.name , and price up to their parent, product .

Promoting the elements does not change their structural position within the XML document, just their position within the content panel.



6. Finally, drag start.date , end.date , and price to the same level of their parent, promotion .

7. To illustrate the entry of data, click to the right of the name attribute and enter a value that conforms to the data type, in this case a string .

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 product to the price list, highlight product in the tag area and then select product from the factory bar. Notice that the new product 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.


| 143

Chapter 3 Adapter Resources Palette

This chapter gives detailed information about the Adapter Resources palette.

Topics

• Specifying Generic Adapter Configurations, page 144

• Generic Adapter Configuration Reference, page 156

• Services Reference, page 160

• Custom Log Sink Reference, page 170

• Sessions Reference, page 174

• Transaction Control and Advisory Reference, page 184

• Folder Reference, page 187

• Endpoint Reference, page 191


144 | Chapter 3 Adapter Resources Palette

Specifying Generic Adapter Configurations

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

OverviewThe Generic Adapter Configuration resource and the associated Adapter Resources 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.

Adapters and Schema Resources

Schema used by an adapter are defined separately from the Generic Adapter Configuration . However, resources in the Generic Adapter Configuration point to adapter schema resources. For example, when you define a service such as a publication service, you need to define the schema that describes the data that will be published. When you save the project, both the adapter configuration and the corresponding schema are saved.

For information on configuring adapter schemas, see Chapter 4, Adapter Schema Palette. You can access this guide via Help > Help For > Adapter Schemas.


Specifying Generic Adapter Configurations | 145

Configuring a New Adapter InstanceTo create an adapter configuration, follow these steps:

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

6. Add operations and, optionally, standard log sinks. An overview is given in this chapter:

— Adding Services to Your Adapter on page 145

— Adding Custom Log Sinks to Your Adapter on page 147

Adding Services to Your AdapterAdapter services are an abstraction useful for configuration of already existing adapters and they are therefore used in the Generic Adapter Configuration . Adapter services do not map directly to any objects used by a TIBCO Adapter SDK program. Instead, an adapter service is an aggregate of an endpoint and the corresponding session and points to the schema used by the endpoint.

Decide now whether you need to perform advanced logging. • If the adapter doesn’t use custom roles, use the Logging tab to specify logging

information.

• If the adapter uses custom roles, click the Use Advanced Logging check box, and use the Log Sinks folder later to define your sinks. See Custom Log Sink Reference on page 170.

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.



The following types of services are supported:

• Publication service

• Subscription service

• Request-Response service

• Request-Response Invocation service

To add a service to an adapter configuration:

1. In the project tree, select the adapter, then open the Adapter Services folder.

2. In the palette panel, select one of the services, for example, a Publication Service , and drag it into the design panel.

3. In the configuration panel give the service a name and choose the transport type.

4. To provide some additional information about the transport, click the Transport tab. What is displayed depends on the transport type you selected for the service. The screen shot below shows the options available for the default transport, a TIBCO Rendezvous Certified transport. See Services Reference on page 160 for detailed information on the individual services and different Transport tab content.



5. If the schema that determines the data used by the service has already been defined, click the Schema tab, then click the browse icon (binoculars) and select the schema resource in the dialog that appears.

6. Click Apply.

TIBCO Designer creates the service instance. If you need to perform additional customizations, you can open the Advanced folder and do it there. See Advanced Adapter Configuration on page 147.

Advanced Adapter ConfigurationAfter you have created a service, you can perform additional adapter customization as follows:

• If information about the session and endpoint cannot be set directly in the service, you can go to the Sessions folder and configure the session and endpoint there. See Sessions Reference on page 174 and Custom Log Sink Reference on page 170.

• If you wish to add custom log sinks, click Use Advanced Logging in the Logging tab for the adapter, then add individual sinks as needed. See Custom Log Sink Reference on page 170.

• If you are using an RVTX session, you can add transaction pools to your adapter. Regardless of the type of session, you can add advisories as needed. See Transaction Control and Advisory Reference on page 184.

• If your adapter takes an extraordinary amount of time to load, you may specify a loadURL in the Metadata URL folder. See Metadata URLs Folder on page 190. In that case, you also need to specify the URL for the location of schema, so the adapter can load them as needed at runtime. You do that from the Adapter’s Startup tab.

Adding Custom Log Sinks to Your AdapterIf your adapter uses only file sinks and stdio sinks, you configure the sinks using the Logging tab at the adapter instance’s top level. If you want to add additional file or stdio sinks, or network sinks or TIBCO Hawk sinks, follow these steps.

1. Select the adapter, then choose the Logging tab and click the Advanced Logging check box.

You must be sure to assign the appropriate schema to the service. The default, any, is only there as a placeholder.



2. Select the Log Sinks folder.

3. Customize the existing File Sink and stdio Sink if you like. See File Sink, page 171 and stdio Sink, page 172.

4. To add more file sinks or stdio sinks:

a. In the design panel, select the sink, choose Copy, then Paste.

b. Name the sink appropriately.

c. Customize the new sink using the fields in the configuration panel. See Log Sinks Overview, page 170.

5. To add Network sink, which publishes information to TIBCO Rendezvous:

a. Select the Log Sinks folder in the project tree.

b. Drag a Generic Log Sink into the design panel.

c. From the pop-up, choose Network and click Apply.

d. Specify the information, as discussed in Network Sink, page 172.

6. To add a TIBCO Hawk sink, which publishes information to TIBCO Hawk:

a. Select the Log Sinks folder in the project tree.

b. Drag a Generic Log Sink into the design panel.

c. From the pop-up, choose Hawk.

d. Specify the information, as discussed in Hawk Sink, page 173.

Adding Extended Properties to Your AdapterIf the existing configuration GUI does not provide the resource you need for some custom configuration, you can add extended properties to your adapter. You can also remove existing attributes or properties using the Delete icon.

You have the following options, discussed in this section.

• Specifying Values for Existing Properties

• Adding Properties

• Deleting Items

Terminology

Keep in mind the following terminology used to describe repository content.

• An object contains attributes.



• An attribute is a named association list. Inside the association lists are name:value pairs which are properties of the attribute.

• As a result, you add an association list to an object, then name it and have an attribute.

Adding Properties

To add an extended property to your adapter, follow these steps:

1. Select the top-level adapter configuration object.

2. Choose Resources > Edit Extended Properties.

3. Use the icons in the Edit Extended Properties dialog to add properties.

You can perform the following operations.

For an example, see Adding Custom Hawk Microagents to Your Adapter on page 150.

Deleting Items

Specifying Values for Existing Properties

To specify a value for an existing property:

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.

You can delete an object, association list, or attribute by selecting it, then clicking the delete icon.



1. Select the property by triple-clicking it.

2. Enter a value of your choice. Note that double-quotes are automatically added when you press Return.

Adding Custom Hawk Microagents to Your AdapterTo add a custom Hawk Microagent to your adapter, you must edit the adapter’s XML file.

The following example shows the elements and attributes required for a custom Hawk Microagent. See the sdk/pubsub example for the actual XML:

+ hawk - help=Java SDK Example pubsub - microAgentName=hawkagent - sessionName = hawkSession + method - help = Retrieve Color Information - name = getColor (this must match the method name in code) - type = INFO + outputParameter - help = Color Information - name = color - type = string (this must match the method's return

type in code) + method - help = Set Color Information - name = setColor (this must match the method name in code) - type = ACTION + inputParameter - help = set color Information - name = color - type = string (this must match the method parameter

type in code)

A Note on Global Variables In many fields in the configuration panel, global variables surrounded by %% are used. In most cases, you can change these global variables using the Global Variables tab in the project panel. See TIBCO Designer User’s Guide for information.

Do not set values for the %%InstanceId%% and %%AppName%% global variables. The variables are set at runtime by run-time adapters.



Using a Message FilterThe Message Filter resource allows developers to transform inbound and/or outbound messages for any adapter built with the Adapter SDK. It could be used, for example, for performing localized transformations using XSLT.

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 MData::toXML() 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 MTransformationPlugin 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 Message Filter resource into the design panel. Name it appropriately for clarity.

2. Specify the name of the implementing class in the Implementation field.

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.



3. In the design panel, add or remove attributes as follows:

a. In the toolbar, click the Add Attribute icon.

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 Generic Adapter Configuration resource and choose the Configuration tab.

2. Click the Browse button next to the Message Filter field and select the Message Filter 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 teststring .

In C++: pMProperties->getValue( pMApp->getAppName() +"/deployment/transformationPlugin/attributes/test", myMStringProp);

In Java: myStringProp =mapp.getConfigProperties().getString(app.getAppParameters().getAppName() + "/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 FALSE to stop message flow.

Testing Your Adapter Using Adapter TesterThe adapter tester is a tool that can be used for testing adapters.

A programming example is included in the TIBCO Adapter SDK Programmer’s Guide.

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.

Setup for Testing TIBCO Adapters

If the adapter you are trying to test is a TIBCO adapter, the adapter tester simplifies the configuration required from you to run the adapter. Provide the following information:

A TRA template and other adapter arguments will be provided automatically by the tester tool.

If the adapter specifies global variables, you can enter values in the window that is displayed.

Working directory

Click Browse to supply the directory. The tester creates the 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 executable

Choose the adapter from the pop-up. Make sure that the 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.



Setup for Testing Custom Adapters

If your adapter is an adapter configured using Generic Adapter Configuration GAC or a custom adapter that the TIBCO installer does not recognize, you need to provide the following information:

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 Custom Shell Command 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.

Adapter Tester may work with GAC and other custom type adapters, however, TIBCO only supports this feature on packaged adapters.

Working Directory

Working directory from which to execute the adapter. Click Browse to select the directory. See Setup for Testing TIBCO Adapters for more information.

Adapter Executable

Name of the executable for the adapter. Click Browse to select the executable. See Setup for Testing TIBCO Adapters for more information.

Arguments Arguments passed to the adapter executable. The last argument should be '--propFile ', the TRA template file containing information necessary for startup of the adapter will be the last argument provided to the operating systems shell.

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.



Using Adapter Tester

To use Adapter Tester, follow these steps:

1. Choose Tools> Show Adapter Tester

All adapter instances configured in the project are displayed.

2. Select the adapter instance to test and provide the appropriate information in the Run Settings tab. See Setup for Testing TIBCO Adapters and Setup for Testing Custom Adapters for information.

3. Click Start.

When the adapter is started, a green dot highlights the running adapter. The display changes to the Console tab. You can now observe the adapter as it executes. The Start button becomes a Stop button.

4. Click Stop when you wish to stop adapter.

The button changes its name to Start and the green dot disappears.

Note under Java 1.3.x on windows you may see a Command Prompt window. This is normal. If you close the window, the adapter process will be terminated.



Generic Adapter Configuration Reference

When you drag a Generic Adapter Configuration into the design panel, or load a legacy adapter into TIBCO Designer, the configuration panel allows you to specify information about the adapter.

This section is a reference for the information you supply for a generic adapter in the configuration panel.

Configuration TabThe Configuration tab allows you to specify the following information:

Two buttons at the bottom of the Configuration tab allow you to change configuration values.

Logging TabThe Logging tab allows you to specify your logging preferences and information. You have two choices:

Instance Name Name of the adapter instance. This name corresponds to the adapter instance configuration object stored in the tibco/private area of TIBCO Repository.

Version Version of the adapter repository. To change the default, click the Change Version button at the bottom of the page.

SDK AppName Short name of the adapter used in the source code.

Description Optional description of the adapter.

Message Filter Allows you to specify a java class that performs manipulations on incoming and outgoing data. For more information, see the Using a Message Filter on page 151.

Change Version Allows you to change the adapter repository version.

Edit Adapter XML

Allows you to edit the raw adapter xml configuration. You should use the palette features to edit the adapter. You are responsible for making sure the configuration is valid.


Generic Adapter Configuration Reference | 157

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

Startup TabThe Startup tab allows you to specify startup information for your adapter.

Use Advanced Logging

When this check box is selected, you configure log sink resources from the Log Sinks folder of the adapter’s Advanced folder. See Custom Log Sink Reference on page 170.

Log to Standard I/O Sends logging information to standard I/O.

Log File Sends logging information to the specified file. See A Note on Global Variables, page 150 for information on the value.

Log Info Messages Sends all messages of type INFO to the specified location(s).

Log Debug Messages Sends all messages of type DEBUG to the specified location(s).

Log Warning Messages

Sends all messages of type WARNING to the specified location(s).

Log Error Messages Sends all messages or type ERROR to the specified location(s).

Show Startup Banner

If checked, a banner is displayed when the adapter is started.

Metadata Search URL

Click the browse icon to specify a previously defined Metadata Search URL for this adapter. See Metadata URLs Folder on page 190 for information on defining a Metadata Search URL.



Monitoring TabThe Monitoring 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.

Enable Standard MicroAgent

If true, a standard TIBCO Hawk microagent is available for this adapter. Its name is COM.TIBCO.ADAPTER . Default is false.

Standard MicroAgent Name TIBCO Hawk microagent name. Defaults to COM.TIBCO.ADAPTER .

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

Enable Class MicroAgent If true, an adapter-specific TIBCO Hawk microagent is available for this adapter. Its name is COM.TIBCO.ADAPTER .adaptername.

Class MicroAgent Name Redefines the name for the adapter-specific agent. Defaults to COM.TIBCO.ADAPTER.adgeneric.%%Deploym

ent%%.%%InstanceId%% . See A Note on Global Variables, page 150 for information on the value.

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.


Generic Adapter Configuration Reference | 159

Default MicroAgent Session

TIBCO Rendezvous session to be used for TIBCO Hawk microagents by default. If not defined, the SDK creates a default session on RV service 7474 (the default for TIBCO Hawk).



Services Reference

The Adapter Services folder contains four adapter services for drag-and-drop configuration. This chapter is a reference to these services. For information on creating an adapter services, see Adding Services to Your Adapter on page 145.

Publication ServiceWhen 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

Transport Tab (Rendezvous Transport)

Name Name of the service.

Description Optional description of the service.

Transport Type Either Rendezvous for TIBCO Rendezvous or JMS for TIBCO Enterprise Message Service. The transport type you choose affects the contents of the Transport tab.

Message Subject

Subject with which this publisher will send out messages. Do not change the subject unless you understand TIBCO Rendezvous requirements.

Reply Message Subject

Reply subject for this publication service.

Quality of Service

Choose Certified (the default), Reliable , or Transactional to create a service of that type.


Services Reference | 161

Transport Tab (JMS Transport)

Wire Format Choose Active Enterprise Message , Rendezvous Message or XML Message , depending on the format the application to which the adapter publishes requires.

Session Reference

When you create a service, TIBCO Designer creates a corresponding session resource in the Sessions folder of the Advanced folder and displays it in this field. If you have explicitly created a custom session of the same type, you can click the Browse icon to replace the autocreated session.

Note: It is not usually appropriate to change the session for a service. Edit the service instead.

Endpoint Reference

When you create a service, TIBCO Designer creates a corresponding endpoint resource in the Sessions folder of the Advanced folder and displays it in this field. If you have explicitly created a custom endpoint of the same type, you can click the Browse icon to replace the autocreated endpoint.

Note: It is not usually appropriate to change the endpoint for a service. Edit the service instead.

Destination Topic or queue to which you wish to send the message.

Reply Destination

Topic or queue where reply messages are sent.

Wire Format If a JMS transport is used, the wire format is always XML Message.

Connection Factory Type

Choose Queue or Topic .

Delivery Mode Choose Persistent or Non-Persistent.



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 ServiceWhen 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):


• Transport Tab (TIBCO Rendezvous Transport)


• Schema Tab

Configuration Tab

Session Reference



Endpoint Reference


Note: It is not usually appropriate to change the endpoint for a service.





Transport Tab (TIBCO Rendezvous Transport)


Message Subject

Subject on which this subscriber will listen for messages. Do not change the subject unless you understand TIBCO Rendezvous.

Quality of Service

Choose Certified (the default), Reliable , Transactional , or Distributed Queue to create a service of that type.

Wire Format Choose Active Enterprise Message , Rendezvous Message , or XML Message depending on the format of the application to which the adapter publishes requires.

Session Reference



Endpoint Reference






Schema Tab


Request-Response Invocation ServiceAn ActiveEnterprise request-response invocation service takes on the role of the client in an ActiveEnterprise operation. Provide the information for the following tabs to configure the service:

Destination Topic or queue from which you receive messages.

Wire Format If a JMS transport is used, the wire format is always XML Message .



Delivery Mode Choose Durable or Non-Durable .

Session Reference



Endpoint Reference








• Schema Tab

Configuration Tab


Name Name of the request-response invocation service.



Message Subject

Subject with which this publisher will send out messages. Do not change the subject unless you understand TIBCO Rendezvous.

Quality of Service

Choose certified or reliable, depending on the level of reliability you require.

Wire Format For ActiveEnterprise operations, only ActiveEnterprise Message format is allowed.

Session Reference






Endpoint Reference



Destination Topic or queue to which you wish to send the message.




Delivery Mode Choose Persistent or Non-Persistent .

Session Reference



Endpoint Reference





Schema Tab


Request-Response ServiceAn 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:




• Schema Tab

Configuration Tab





Message Subject

Subject on which this subscriber will listen for messages. Do not change the subject unless you understand TIBCO Rendezvous.

Quality of Service

Choose Certified (the default), Reliable , or Distributed Queue to create a service of that type.

Wire Format For ActiveEnterprise operations, only ActiveEnterprise Message format is allowed.




Session Reference



Endpoint Reference



Destination Topic or queue from which the message is coming.




Delivery Mode Choose Durable or Non-Durable .

Session Reference


Note: It is not usually appropriate to change the session for a service.



Schema Tab


Endpoint Reference


Note: It is not usually appropriate to change the endpoint for a service.



Custom Log Sink Reference

The Log Sinks folder allows you to configure advanced logging behavior.

This discusses the following log sink topics:

• Log Sinks Overview

• File Sink

• stdio Sink

• Network Sink

• Hawk Sink

• Adding Roles to Sinks

Log Sinks OverviewThe TIBCO Adapter SDK allows programmers to define traces with different roles and sends them to sinks with the corresponding role.

You can fine-tune where and when different types of information are sent. First you use TIBCO Designer to define sinks and map each sink to one or more roles.

Each time the program calls a tracing method, it has to explicitly or implicitly specify one or more roles. Each sink that has been mapped to that role receives that message if the role has been turned on. This way, the output information level can be tuned via modifications to the adapter configuration. To reduce the amount of information, roles can be turned off for the adapter configuration using TIBCO Designer.

Four types of sinks are predefined and configurable from the Log Sinks folder. They are discussed in this chapter:

• File Sink on page 171

• stdio Sink on page 172

• Network Sink on page 172

• Hawk Sink on page 173

You can also define a sink that uses a custom role. This is discussed in Adding Roles to Sinks on page 173.

For basic logging behavior, use the Logging tab of the adapter instance. See Logging Tab on page 156.


Custom Log Sink Reference | 171

File SinkFor a file sink, you specify the following information:

The default file sink that is part of each adapter has those roles predefined that were selected when you turned on Advanced Logging . If you create additional file sinks, you can add roles. See Adding Roles to Sinks on page 173

Understanding File Count and File Limit

If you have specified a file sink in your configuration, your SDK-based adapter will go through these steps:

1. Creates a file with no extension using the specified filename.

2. Writes to that file until it reaches the size specified in File Limit .

3. When File Limit 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.

Name Sink name of this file sink.

File Name Global variable that includes the path and name of trace file. Extension .log is suggested.

File Limit (bytes)

Maximum size of the file, in bytes. Default is 30000. Maximum is 2147483647 bytes.

File Count Number of rollover files. Default is 3.

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.

Description Optional description of this file sink.



5. The adapter repeats this process until it reaches the number of files specified in File Count .

stdio Sink For a stdio Sink , you specify the following information.

Network SinkTo add a network sink:

1. Select the Log Sinks panel.

2. Drag a Generic Log Sink into the design panel.

3. In the configuration panel, choose Network from the pop-up menu.

4. Specify the network sink’s attributes.

5. Add roles. See Adding Roles to Sinks on page 173.

The adapter overwrites the file with the highest number, that is, the oldest file, when the number of files reaches File Count and that last file reaches File Limit . To avoid that, set either File Count or File Limit to a sufficiently large value.

Name Name of this sink.

Output Stream Select stdio or stderr. If you select stderr, it remains selected even when you turn off Advanced Logging .

Description Optional description of this sink.

Name Sink name of this network sink.

Session Click the Browse icon and select one of the sessions you defined.

Subject Subject of TIBCO Rendezvous messages to be sent.

Description Optional description of this sink.


Custom Log Sink Reference | 173

Hawk SinkA Hawk sink sends messages to TIBCO Hawk. To add a Hawk sink:

1. Select the Log Sinks panel.

2. Drag a Generic Log Sink into the design panel.

3. In the configuration panel, choose Hawk from the pop-up menu.

4. Specify the Hawk sink’s attributes.

5. Add roles. See Adding Roles to Sinks on page 173.

Adding Roles to SinksFor sinks that were defined for the adapter before Advanced Logging was turned on, one Role resource is included for each role that was turned on.

If you wish to add additional roles, or if you wish to add roles to newly created sinks, you have the following options:

To use an existing role, control-drag it into the sink.

To create a new role, follow these steps:

1. Select the sink and drag a Generic Role into the design panel.

2. If you wish to add a custom role, type the name of the role into the available field and press Enter, then click Apply.

3. If you wish to add one of the predefined roles, choose the role from the pop-up, then click Apply.

Name Name of this Hawk sink.

MicroAgent Name

Name of the microagent for traces from this Hawk sink.

Description Optional description of the sink.



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 Advanced folder of the Generic Adapter Configuration . This section is a reference to the sessions included with TIBCO Designer.

The following sessions are discussed:

• RV Session

• RVA Session

• RVCM Session

• RVCMQ Session

• RVTX Session

• JMS SessionSessions encapsulate stateful connections to a messaging source (such as a TIBCO Rendezvous daemon), database, or remote server.

To Create a Session

1. Select the Adapter Services folder in the project panel.

2. Drag a service (e.g. a Publication Service) into the design panel.

3. Specify the transport type and fill in the information in the Transport tab.

4. TIBCO Designer creates the service and creates a corresponding session and endpoint in the Advanced folder.

Creating sessions explicitly is not recommended. TIBCO Designer creates a session and an endpoint for you when you create a service. Under certain situations, expert users may need to create sessions explicitly.

For TIBCO Rendezvous configuration, you must be familiar with TIBCO Rendezvous administration, as discussed in the TIBCO Rendezvous documentation set.


Sessions Reference | 175

RV SessionFor TIBCO Rendezvous sessions, the configuration panel includes the following information.

RVA SessionFor RVA sessions, the configuration panel includes the following information.

To edit the global variables used in this panel, click the Global Variables tab in the project panel in the upper left quadrant. For more information, see TIBCO Designer User’s Guide.

Name Name of the TIBCO Rendezvous session.

Description Optional description of the session.

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.

Daemon Global variable that specifies the TIBCO Rendezvous daemon for this session. Default is the empty string.

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.

To edit the global variables in this panel, click the Global Variables tab in the project panel in the upper left quadrant. For more information, see TIBCO Designer User’s Guide.

Name Name of the TIBCO Rendezvous session.




RVCM SessionFor RVCM sessions, the configuration panel includes the following information.

Host Global variable that specifies the name of the host. If no host is specified or the empty string is provided, the local host machine is the default.

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.

To edit the global variables, click the Global Variables tab in the project panel in the upper left quadrant. For more information, see TIBCO Designer User’s Guide.

Name Name of the rvCmSession .



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 SessionFor RVCMQ sessions, the configuration panel includes the following information.

CM Name Used to identify the delivery tracking session. It must be unique across the entire network. See A Note on Global Variables, page 150 for information about this field.

Relay Agent Relay agent for this session.

LedgerFile Global variable that points to a ledger file. If the variable’s value is a valid filename, the session uses a file-based ledger. See A Note on Global Variables, page 150 for information about this field.

Synchronous Ledger Writes

If True , then operations that update the ledger file do not return until the changes are written to the storage medium.

If False , the operating system writes changes to the storage medium asynchronously.

Default Time Limit (ms)

Default timeout value for all associated publishers, in milliseconds. Defaults to 0 (infinite).

Require Old Messages

Indicates whether a persistent correspondent requires delivery of messages sent to a previous session with the same name for which delivery was not confirmed. Its value affects the behavior of other delivery-tracking senders.

If checked, and if the name attribute is non-NULL, then this session requires certified senders to retain unacknowledged messages sent to this persistent correspondent.

If unchecked, messages are not retained.


Name Name of the RVCMQ session.








CMQ Name Sequence of global variables that specifies the name of the queue.

Complete Time (ms)

If the complete time is non-zero, the scheduler waits for a 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 Heartbeat (ms)

The scheduler session sends heartbeat messages at this interval (in milliseconds).

All member sessions in the queue must specify the same value for this parameter. Acceptable values are the unsigned 32-bit integers (except zero). Default is 1000.

Scheduler Weight

Represents the ability of this session to fulfill the role of scheduler, relative to other members of the same queue. The queue members use relative scheduler weight values to elect one member as the scheduler. Members with higher scheduler weight take precedence.

Acceptable values range from 1 to 65545. Default is 1.



RVTX SessionFor TIBCO Rendezvous TX sessions, the configuration panel includes the following information.

Scheduler Activation (ms)

When the heartbeat signal from the scheduler has been silent for this interval (in milliseconds), the queue member 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.

Listener Weight

Relative listener weights assist the scheduler in assigning tasks. When the scheduler receives a task, it assigns the task to the available listener with the greatest listener weight. Default is 1.

Listener Tasks Listener tasks for this session. Default is 1.


Name Name of TIBCO Rendezvous TX session.







JMS SessionFor JMS sessions, the configuration panel includes the following information.


Transactional Name

Sequence of global variables used to identify the transaction session. This name must be unique across the entire network.

Default Time Limit

Default timeout value for all associated publishers, in milliseconds. Defaults to 0 (infinite).

Operation Timeout

Maximum amount of time that a transaction will wait for the RVTX daemon to reply.


Name Name of the JMS session.


JNDI Lookups If checked, a JMDI Server is used. In that case, a number of fields in this tab change correspondingly.

Use SSL If this option is checked, the adapter connects to the JMS server using SSL. For this case, an SSL tab becomes available that lets you specify SSL settings. See Configure SSL Dialog below.

(JNDI) Connection Factory Type

Specifies the type of connection to the JMS server or the JNDI server. Choose topic or queue.

Note: if you already specified the connection factory type for a service, you cannot change it for the session.

(JNDI) Connection Factory Name

Name of the connection factory.



Configure SSL Dialog

If you check Use SSL in the basic configuration tab for a JMS session, a Configure SSL button becomes available. When you click the button, an SSL configuration dialog prompts you for the following information:

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.

Advanced Tab

If you wish, you can also provide the following advanced information: i

(JNDI) Connection Username

Username for logging into the JMS server or JNDI server.

(JNDI) Connection Password

Password for logging into the JMS server or JNDI server.

(JNDI) Provider URL URL of the server.

Trusted Certificates Folder

Click the browse icon and select the folder in which 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.

Identity Click the browse icon and select the identity to be used by this transport. See Chapter 5, Managing Trusted Certificates, on page 107 in TIBCO Designer User’s Guide.

Trace If checked, SSL tracing is turned on.

Debug Trace If checked, the SSL debug trace is turned on.



OpenSSL v3.0 Cipher Suite List

The following list is available on http://www.openssl.org/docs/apps/ciphers.html#CIPHER_SUITE_NAMES

Verify Host Name

This field specifies that the host name of the HTTP server 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 Name

This name must match the name in the certificate.

Strong Cipher Suites Only

If checked, only strong Cypher Suites are allowed. See OpenSSL v3.0 Cipher Suite List on page 182 for a list of available suites.

Table 15 Cipher suite list

Suite Name OpenSSL Name E4JMS ClientSSL_RSA_WITH_NULL_MD5 NULL-MD5 C

SSL_RSA_WITH_NULL_SHA NULL-SHA C

SSL_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 C & Java

SSL_RSA_WITH_RC4_128_MD5 RC4-MD5 C & Java

SSL_RSA_WITH_RC4_128_SHA RC4-SHA C & Java

SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 C & Java

SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA C

SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA C & Java



SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA C & Java

SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA C & Java

SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA C & Java

SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA C

SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA C & Java

SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA C & Java

SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA C & Java

SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA C & Java

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

Table 15 Cipher suite list

Suite Name OpenSSL Name E4JMS Client



Transaction Control and Advisory Reference

When you select the Transaction Control folder, you can choose a transaction control type resource, which can then be used in conjunction with a control pool resource. The folder is found under the GenericAdapterConfiguration Advanced folder.

When you select the Advisories 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 ControlsAdapters use transaction control pools in conjunction with RVTX. To specify a transaction control pool, follow these steps:

1. Select the Transaction Controls folder.

2. From the palette panel, choose a Transaction Control Pool resource and drag it into the design panel.

3. In the configuration panel, select the appropriate type from the pop-up, then click Apply.

4. Specify configuration information as appropriate. For more detail, see the appropriate control pool.

— JDBC Control Pool

— ODBC Control Pool

— Null Control Pool

— Simple Control Pool

— XA Control Pool

— MTS Control Pool

JDBC Control Pool

For a JDBC Control Pool , you can specify the following information (fields in bold are required):

Name Name of this control pool.


Transaction Control and Advisory Reference | 185

ODBC Control Pool

For an ODBC Control Pool , you can specify the following information

Null Control Pool

For a Null control pool , you can specify the following information

User ID ID of the user who logs into the database.

Password Password of the user who logs into the database.

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.

Transaction ID Table

Name of the database table where transaction commit status information is stored. Used internally by TIBCO Rendezvous TX.

Maximum Controls Upper bound for the number of transaction controls that can be created.

Description Optional description of this transaction control pool.

Name Name of this ODBC control pool.


Transaction ID Table

Name of the database table where transaction commit status information is stored. Used internally by TIBCO Rendezvous RVTX.


Name Name of this Null control pool.




Simple Control Pool

For a simple control pool, you can specify the following information

XA Control Pool

For an XA control pool , you can specify the following information

MTS Control Pool

For an MTS control pool, you can specify the following information

AdvisoriesYou can create one or more advisories and associate it with a session in your application. Follow these steps:

1. Select the Advisories folder in the project tree.

2. From the palette panel, drag an Advisory resource into the design panel.

3. In the configuration panel, specify a name and a subject.

4. To associate a session with the advisory, select the advisory in the project tree, then drag a session into the design panel.

Name Name of this simple control pool.



Name Name of this XA control pool .


Name Name of this MTS control pool .



Folder Reference | 187

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 Generic Adapter Configuration .

• Adapter Services Folder

• Advanced Folder

• Log Sinks Folder

• Sessions Folder

• Timers Folder

• Transaction Controls Folder

• Advisories Folder

• Metadata URLs Folder

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



Figure 58 TIBCO Designer Generic Adapter Configuration Default Folders

Adapter Services FolderThe Adapter Services folder is part of every adapter configuration. It is the starting point for configuration. You select services and drag them into the design panel, then configure the services in the configuration panel. See the online help for the individual services for additional information.

Each time you configure a service, TIBCO Designer creates the corresponding session and endpoint in the Advanced folder.

Advanced FolderThe Advanced 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 Adapter Services folder. They may then access the resources in this folder for certain custom configuration.


Folder Reference | 189

Log Sinks FolderThe Log Sinks folder stores log sinks for an adapter.

You have two options for specifying logging for your adapter:

• For basic logging, use the Logging tab for the adapter instance. See Logging Tab, page 156 for information. If you are using this Generic Adapter Configuration to configure an already existing adapter that was loaded into it, your adapter may include additional logging information.

• For advanced logging, click Use Advanced Logging, in the adapter’s Advanced Logging tab, then specify log sinks in the Log Sinks folder. See , Custom Log Sink Reference.

Sessions FolderThe Sessions 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 Sessions folder if customization not available for the service is required. See , Sessions Reference and , Custom Log Sink Reference.

Timers FolderThe Timers 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.

Transaction Controls FolderThe Transaction Controls folder stores transaction controls for an adapter.

If you configure an adapter for which a palette is predefined, and transaction controls 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 Transaction Controls on page 184.



Advisories FolderThe Advisories 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.

Metadata URLs FolderBy default, an SDK-based adapter loads all metadata upon startup. This is the recommended behavior.

If your adapter needs an extraordinary amount of time to load all metadata, you may specify a metadata URL. The adapter will then load only those metadata to which the URL points

Load URL Resource

The Load URL resource allows you to specify a directory that the adapter will search for schema classes upon startup.

You specify the locations where the adapter will look for additional metadata (the metadata search URL) directly in the Startup 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 Load URL . To do so, click Browse to choose the location. See the Chapter 4, Adapter Schema Palette, for more information.


Endpoint Reference | 191

Endpoint Reference

Endpoints correspond closely to the publisher and subscriber, request-response invocation server, or request-response server objects used by an Adapter SDK program. This section provides reference information for all endpoints.

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 OverviewWhen 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 Generic Adapter Configuration 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 EndpointsA 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

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.



are supported. The session for a publisher determines the wire format it can use. For JMS sessions, you can also change the delivery mode.

TIBCO Rendezvous PublishersTIBCO Designer supports RV, RVA, RVCM, and RVTX sessions. For each type of session, you can create a corresponding publisher.

For TIBCO Rendezvous publishers, following wire formats are supported at present:

• Rendezvous Message is a TIBCO Rendezvous message which may have any contents, not necessarily following the TIBCO ActiveEnterprise wire format.

• ActiveEnterprise Message is the TIBCO ActiveEnterprise standard wire format. It can include metadata information.

• XML Message uses aeXml message format.

TIBCO Enterprise Message Service Publisher

TIBCO Designer supports JMS sessions and will create the appropriate session for you when you create a service. The Connection Factory Type (Topic or Queue) and the Delivery Mode (Persistent or non-Persistent) you assign to the service determine the session and endpoint that is created.

TIBCO Rendezvous Publisher

For an RV Publisher, you supply the following information:

Creating sessions explicitly and adding publishers 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.

Name Name of this publisher.

Description Optional description of the publisher.

Endpoint Type Choose from the pop-up, which displays the allowed types for the current session.



RVCM Publisher

For an RVCM publisher, you supply the following information:

Wire Format Rendezvous Message , ActiveEnterprise Message , or XML Message . Default is ActiveEnterprise Message . If you choose ActiveEnterprise Message , control information is included with the message. If you choose Rendezvous Message , no control information is included with the message but control information may be included with the data.

Subject Subject with which this publisher will send out messages.

Reply Subject Reply subject for this publisher.







Message Timeout (ms)

Time after which the message is discarded from the ledger file. Default is 0 seconds, meaning that the timeout is infinite.

Preregistered Listeners

Comma-separated list of listeners preregistered for this publisher. Refer to each listener using the CmName of the session.



RVTX Publisher

For a TIBCO Rendezvous TX publisher, you can supply the following information:

JMS Topic Publisher

For a JMS publisher associated with a JMS session using a Topic Connection Factory, you can supply the following information:







Message Timeout

Message timeout for this publisher.



Endpoint Type For JMS publishers, there are no endpoint type choices.

Delivery Mode Either persistent or non-persistent.

Destination Destination used by this publisher.

Reply Destination Reply destination for this publisher.

Message Timeout Message timeout for this publisher.



JMS Queue Publisher

For a JMS publisher associated with a JMS session using a Queue Connection Factory, you can supply the following information:

Subscriber EndpointsSubscribers 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.

RV Subscriber, RVCM Subscriber, RVCMQ Subscriber, RVTX Subscriber

You supply the following information for each type of subscriber using TIBCO Rendezvous as the transport:



Endpoint Type For JMS publishers, there are no endpoint type choices.

Delivery Mode Always non-persistent. The mode persistent cannot be used with JMS Queue publishers.

Destination Destination used by this publisher.

Reply Destination Reply destination for this publisher.

Message Timeout Message timeout for this publisher.

Creating sessions explicitly and adding subscribers 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.

Name Name of this subscriber.

Description Optional description of the subscriber.



JMS Subscribers

You supply the following information for subscribers using JMS as a transport:

Client / Request-Response Invocation Service EndpointsRequest-response invocation (client) services are used by ActiveEnterprise operations that communicate with a remote or local server. You can define request-response invocation services for each type of session.




Listen Timeout (ms)

If no message is received after this amount of time, the adapter performs any actions specified in the program for that case. Default is 0

Name Name of this subscriber.

Description Optional description of the subscriber.

Endpoint Type For JMS Subscribers, there is no choice to make.

Delivery Mode Either durable or non-durable. Note: For subscribers using a queue session, durable is not an option.

Destination Destination for this JMS subscriber.

Auto-confirm If this box is checked, the SDK automatically confirms events for this subscriber.



See "The SDK Operation Model" in TIBCO Adapter SDK Programmer’s Guide for more information.

TIBCO Rendezvous Request-Response Invocation Service

You can create a TIBCO Rendezvous Request-Response Invocation Service for RV or RVCM. Each Rendezvous Request-Response Invocation Service allows you to specify the following information:

JMS Request-Response Invocation Service

Each JMS Request-Response Invocation Service allows you to specify the following 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.

Name Name of this client.

Description Optional description of this client.

Endpoint Type Choice of endpoint types for the session to which the client currently belongs.

Subject Subject with which this client communicates with the server.

Invocation Timeout (ms)

If no reply is received by the client after this timeout, the application gets an error notification.

Name Name of this client.

Description Optional description of this client.

Delivery Mode Non-Persistent or Persistent.


Destination Destination used to communicate with the server.

Invocation Timeout (ms)

If no reply is received by the client after this timeout, the application gets an error notification.



Server / Request-Response Service EndpointsRequest-Response services are used by ActiveEnterprise operations that communicate with a remote or local client (request-response server). You can define request-response services for each type of session.

See "The SDK Operation Model" in TIBCO Adapter SDK Concepts for more information.

TIBCO Rendezvous Request-Response Service

You can create a TIBCO Rendezvous Request-Response Service for RV, RVCM, or RVCMQ.

Each server allows you to specify the following information:

JMS Request-Response Service

Each server allows you to specify the following information:

Creating sessions explicitly and adding servers 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.

Name Name of this server.

Description Optional description of this server.


Subject Subject with which this server communicates with clients.

Name Name of this server.

Description Optional description of this server.


Delivery Mode Either durable or non-durable.

Destination Destination used to communicate with the client.



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

1. Open the Timers folder

2. Drag a Timer from the palette panel into the design panel.

3. Specify configuration information for the timer.

Adding Schema to EndpointsAs a rule, it is best to add schema to endpoints using the Schemas tab of the service. If, however, you must create the session and endpoint directly, follow these steps to add schema:

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.

An alternate approach to adding the schema is to use the Link Resource menu command, as follows:

1. From the menu bar, choose Tools > Resource Tools > Link Resource.

2. Select the schema object as the Field Resource.

3. Select the endpoint as the Field Target.

4. Click OK.

Name Name of this timer.

Interval (milliseconds)

Trigger interval in milliseconds (for repeating timers)

Repeating If checked, this is a repeating timer. If not checked, this is a once-only timer.

Session Reference

Click the Browse icon to associate a session with this timer.


| 201

Chapter 4 Adapter Schema Palette

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

• Understanding Schema Management, page 202

• TIBCO Designer Schema Reference, page 208

• Schema Resource Reference, page 223

• TIBCO Designer Adapter Schema Folders, page 227


202 | Chapter 4 Adapter Schema Palette

Understanding Schema Management

TIBCO Designer is used for configuration of adapters and TIBCO ActiveMatrix BusinessWorks integration projects. TIBCO Designer is used by integration specialists who may be business analysts or programmers that know about the source or target system to which the adapter connects.

Business analysts use TIBCO Designer to configure adapters to get data into and out of another system. The source or destination of the data could be, for example, SAP R/3, PeopleSoft, Siebel or any of the many systems for which TIBCO provides adapters.

How schema management differs depending on the adapter:

• Managing Schema for Standard Adapters With Custom Palettes

• Managing Schema for Adapters that Are Loaded Into GAC

• Managing Schema for Custom Adapters Created with the SDK

Managing Schema for Standard Adapters With Custom PalettesMany adapters are shipped with custom palettes for the adapter. In that case, the configuration process is as follows:

1. Install the adapter on the platform of your choice.

2. During installation, a TIBCO Designer palette for the adapter is placed into the appropriate folder. This palette becomes available the next time you start TIBCO Designer.

Documentation for the adapter becomes available via the Help menu.

3. Configure the adapter using the adapter custom palette. During that process, you define schema data, but you do not use the schema resources discussed in this chapter. For an overview of the process, see Configuring Standard Adapter Endpoints and Schema on page 205.

Managing Schema for Adapters that Are Loaded Into GACIf no custom palette is available for an adapter, you can still load that adapter into TIBCO Designer. When the adapter is loaded, a Generic Adapter Configuration (GAC) instance is created and endpoints and sessions are defined.


Understanding Schema Management | 203

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.

Managing Schema for Custom Adapters Created with the SDKIf you are writing a custom adapter using the TIBCO Adapter SDK, you must define the schema that describe the data the adapter publishes and subscribes to, as discussed in this chapter.

How TIBCO Applications Use Schema DataTIBCO applications use schema data to describe or constrain data or operations used by the application. For example, you can specify that an adapter only subscribes to data of a prespecified type. The data could be restricted to a predefined type, for example an integer or string, or a custom type represented by a class. You could also restrict the operations used by client-server interactions. For operations, you can specify the number of required parameters, their type, the return type, and the exceptions.

Schema data effectively isolate the data description from the application data itself. TIBCO Designer is used to define schema data for a project. The schema can then be used by all resources in the project. For example, assume you want to restrict the data a publisher sends. You can define a schema resource, then point to that resource from the publisher. The program will then use the schema to check whether outgoing data meet the requirements. For client/server operations, you can also define schema that describe operations, their parameters, return types, and exceptions.

Schema BasicsThe 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.

Configuring Standard AdaptersWhen you configure a standard adapter for which a TIBCO Designer palette exists, you do not define schema data. Instead, you configure the publishers,

This document explains schema management but assumes you understand adapter configuration concepts. For example, you should know what an endpoint or a session is.



subscribers, clients, or servers your adapter uses. During that configuration, TIBCO Designer lets you choose the data with which the publisher, subscriber, etc. should work. TIBCO Designer automatically creates the schema objects corresponding to the data you choose. For an example, see Configuring Standard Adapter Endpoints and Schema, page 205.

Working With Legacy and Custom Adapters

You use the Adapter Schema Resources palette in these situations:

• If you load a legacy adapter, for which no palette exists, TIBCO Designer creates a palette using the Generic Adapter Configuration resources. You can then change the schema for the endpoints in that adapter using the Adapter Schema palette.

• If you are creating a custom adapter from scratch, you use the resources in the Adapter Resources palette to define the sessions, endpoints, and other elements. You then have to create schema resources to represent the data the endpoints in your custom adapter work with.

See Defining Custom Adapter Schema on page 206.

Default Schema Resources

A number of schema resources are included in the AESchemas folder by default. These resources represent schema that are recognized by the TIBCO Adapter SDK. They include:

• ae—ActiveEnterprise schema data

• ae folder—Contains default predefined ActiveEnterprise resources, such as MAdvisoryDocument or MBusinessDocument .

• corba—CORBA schema data

• java—java schema data

• sql—SQL schema data

To use any of these resources, you should always first drag an AESchema 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.



Configuring Standard Adapter Endpoints and SchemaThis example illustrates how you choose the schema information in a standard adapter and how TIBCO Designer creates the corresponding resources.

This example configures a PeopleSoft adapter subscriber which retrieves data from a PeopleSoft application.

Follow these steps:

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.

How TIBCO Designer Works With the Schema Data

When you are setting up the PeopleSoft subscriber, TIBCO Designer performs a number of operations:

• Names the subscriber to reflect the component interface to which it subscribes.

• Sets the quality of service appropriate for this component interface.

The exact process differs for each adapter and is discussed in the adapter’s documentation.

Knowledge or understanding of these operations is not necessary or even useful for adapter configuration. They are included for the sake of completeness.



• 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 Custom Adapter SchemaIf you are configuring an adapter for which no palette is available, or if you are creating an SDK-based adapter, you can configure Schema resources using the AESchemas folder.

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 AESchemas folder and double-click the ae folder.

2. From the palette panel, select a Folder resource (General palette) and drag it into the design panel.

3. Name the folder appropriately for your adapter.

4. From the palette panel, select an AESchema resource (Adapter Schemas palette) and drag it into the design panel.

It is highly recommended you use a separate Folder inside AESchemas for each adapter. It can be very helpful, for example, if you limit the data initially loaded by specifying a Metadata URL. See Metadata URLs Folder on page 190.



The AESchema resource contains folders for the classes, sequences, etc. to be used by the adapter. Click the + below the resource in the project tree to see the folder hierarchy.

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



TIBCO Designer Schema Reference

This section contains some introductory information, followed by reference information for each resource in the Adapter Schemas palette.

This section discusses the following topics:• AESchemas Folder

• Adapter Schemas Palette

• Classes

• Operations

• Scalars

• Unions

• Sequences

AESchemas FolderWhen you launch TIBCO Designer, the project tree always includes an AESchemas folder immediately under the top-level folder.

The AESchemas 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 AESchemas folder.

• When you configure a custom adapter, you create schemas inside the AESchemas folder. You then add schema references to the services your adapter provides. Some examples are given in this chapter.

Adapter Schemas PaletteWhen you select an item inside the AESchemas folder, for example, a Classes folder or an individual class resource in the project tree, the Adapter Schema palette is displayed in the palette panel.

When you configure a standard adapter, you do not usually add schema to the adapter explicitly. Instead, you specify configuration information and can then interactively select the data the services manipulate.

This reference is therefore mainly for developers who perform a custom configuration using Generic Adapter Configuration .


TIBCO Designer Schema Reference | 209

You use this palette to define schema for your adapter. See Defining Custom Adapter Schema on page 206 for an example.

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

Defining a Class with AttributesTo define a class that describes data your adapter retrieves or publishes, follow these steps:

1. In the TIBCO Designer project tree, select the AESchemas folder, then the ae folder.

2. Drag a Folder resource into the ae folder displayed in the design panel and name it appropriately for your adapter.

3. Drag an AESchema resource into the folder. Open the AESchema resource and select its Classes folder.

4. In the palette panel, select the Generic Class icon and drag it into the design panel.

5. For the Class Type field, select Schema , 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.

Adding Attributes to a Class

The attributes of the schema class object define the type of data that the schema object you are creating will allow. To add attributes to a schema class, follow these steps:

You cannot add attributes to a class until you have specified its type.



1. Select the class in the project tree.

The palette panel now displays the icons for resources you can add to the class (or the palettes containing the icons).

2. Drag the icon that represents the type of data for this attribute. For example, you could drag a class into the design panel, then click the Browse icon to select the class. Or you could drag a Generic Scalar (found in the Scalar Types palette) and choose the desired type from the pop-up. You have these choices:

Adding Class Attributes, page 210

Adding Union Fields, page 211

Adding Sequence Fields, page 211

Adding Scalar Fields, page 211

3. Specify the following additional information about the attribute:

Keyfield. Select the check box if this attribute represents a key field, or leave it unchecked if it does not.

Default Value. Provide a default value. This property is not available for all attribute types.

Readable. Select the check box to make the attribute readable, deselect otherwise.

Writable. Select the check box to make the attribute writable, deselect otherwise.

4. Click Apply.

Adding Class Attributes

To add an attribute whose value must be a class:

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.

For classes that have superclasses, an attribute or operation must not overload or hide one of the same name in a superclass.



Adding Union Fields

To add an attribute whose value must be a union, you must first have defined one or more Union resources. See Unions, page 218:

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

Adding Sequence Fields

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.


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.

Adding Scalar Fields

To add an attribute whose value must be a scalar, follow these steps:

1. Specify the scalar that should restrict the attribute value, if it does not yet exist.


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.

Defining a Class with OperationsTo define a class that describes data your adapter retrieves or publishes, follow these steps:





5. For the Class Type field, select Operation 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.

Adding Operations to an Operation Class

The following section gives one example for defining an operation. The exact choices you make depend on the operation you want to define.

To add operations to an Operation class, follow these steps:

1. Select the Operation resource in the project tree.

You cannot add attributes to a class until you have specified its type.



2. From the palette panel, drag the Operation 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 AESchema/ae/Scalars folder or a predefined class.

c. Click the One Way check box if this is a one way operation.

3. Select the parameters 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 Generic Scalar into the design panel.

b. Specify a name, the type (String), and optional direction (In).

In—In parameter. Client can set the value and invoke the operation.

In/Out—Both client and server can set the value.

Out—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 Exceptions 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 Generic Class into the design panel.

b. Specify a name and click Browse to select a class.

c. Choose AESchemas/ae/MAdvisoryDocument to indicate this exception returns an MAdvisoryDocument instance.

d. Click Apply.

e. Specify additional exceptions by repeating steps a-d as desired.

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

1. Using TIBCO Designer to describe the operations to be performed. This includes parameters and exceptions for the operations.



2. Using TIBCO Adapter SDK classes to implement the behavior in the application code.

Defining Operations

To define an operation, follow these steps:





5. For the Class Type field, select Operation Schema , then click Apply.

6. Select the Operation Schema class in the project tree. From the palette panel, drag an Operation 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 AESchema/ae/Scalars 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 Parameters 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 Exceptions folder of the operation. From the project tree, drag in the resources representing the exception types.

Defining Operation Parameters

When you define an operation, TIBCO Designer automatically adds two folders:

Operation Parameter Folder

Use this folder to drag in resources representing the parameter types, as discussed in the following sections.



• Parameters of Type Class

• Parameters of Type Sequence

• Parameters of Type Scalar

• Parameters of Type Union

Operation Exceptions Folder

Use this folder to drag in resources representing the exception types, as discussed in the following sections. See Defining Exception Parameters on page 217.

Parameters of Type Class

If you want to add a parameter that has a Schema Class as a type, follow these steps:

1. Create the operation, as discussed in Defining Operations on page 214.

2. In the project tree panel, double-click the Parameters folder.

3. Select a class in the project tree and drag it into the design panel, or click Browse and find the class you want to use.

4. Select the operation direction.

In—In parameter. The client can set the value and invoke the operation.


Out—Only the server can set the value and send the reply back to client.

5. Click Apply.

Your operation now expects a parameter which has the class you selected as its type.

Parameters of Type Sequence

If you want to add a parameter that has a sequence as a type, follow these steps:



3. Select a sequence in the project tree and drag it into the design panel, or click Browse and find the class you want to use.







5. Click Apply.

Your operation now expects a parameter which has the sequence you selected as its type.

Parameters of Type Scalar

If you want to add a parameter that has a scalar as a type, follow these steps:



3. Select a scalar in the project tree and drag it into the design panel, or click Browse and find the class you want to use.





5. Click Apply.

Your operation now expects a parameter which has the scalar you selected as its type.

Parameters of Type Union

If you want to add a parameter that has a union as a type, follow these steps:



3. Select a union in the project tree and drag it into the design panel, or click Browse and find the class you want to use.





5. Click Apply.



Your operation now expects a parameter which has the union you selected as its type.

Defining Exception Parameters

When you define an operation, TIBCO Designer creates an Exceptions folder for you. You can specify the type of exceptions the operation should return as follows:


2. In the project tree panel, double-click the Exceptions folder.

3. Drag the object representing the type of exception you wish to have delivered into the design panel. For example, for an exception of type MAdvisoryDocument, select an MAdvisoryDocument object.

4. Click Apply.

5. Add more exceptions to the operation as needed.

ScalarsWithin TIBCO Designer, the term Scalar refers to a primitive object that describes a data type, such as int , long , char , byte , and date . 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.

When an adapter repository is created, a number of scalar objects are included by default.

In addition, you can work with parameterized primitive data types (for example, ae/fixed , ae/binary , ae/char), where you can derive an infinite number of types from a base type by changing various data type attributes. You can use these types, for example, to create a bounded binary or bounded char type. If there is a base data type, then it will be pre-loaded, but you are required to create any other instances as you need them, just as you would for sequence types.

You can use one of the scalar resources that are already included with TIBCO Designer, or define a custom scalar used by your application.

To define a custom scalar:

1. In the project tree, select one of the folders inside the Scalars folder in the project tree or, to define a new scalar type, create a new folder first.

The resources in the ae folder correspond to the types available for SDK adapters.



2. From the palette panel, drag a Generic 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:

1. In the project tree panel, select the Classes folder.

2. In the palette panel, select a Generic Class and drag it into the design panel.

3. In the configuration panel, select Schema as the class type.

4. To add a scalar attribute, select the new schema class, then drag a Generic Scalar from the palette panel into the design panel.

5. Specify the information about the attribute you have added:

Name—Name of the attribute

Type—Select the appropriate type from the pop-up.

Default Value—Specify the default value for this field. This information is optional and no type checking is performed.

Keyfield—Select if this is a key field.

Readable—Select if you want for this field to be readable.

Writable—Select if you want for this field to be writable.

6. Click Apply.

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

Defining Union Objects

Define one or more Union objects as follows:

1. Select the Union folder.

2. From the palette panel, drag a Generic Union into the design panel.



3. Give the Union a name, then add members to the Union .

Adding Union Members to Union Objects

When you specify the union members for a union, TIBCO Designer creates references to the object you add. This section discusses the process for the different resource types:

• Adding Class Reference Union Members on page 219

• Adding Sequence Reference Union Members on page 219

• Adding Scalar Reference Union Members on page 220

• Adding Union Reference Union Members on page 220

Adding Class Reference Union Members

When you add a class union member to a union, TIBCO Designer creates a class reference. To define union members that are classes, follow these steps:

1. Select a union in the project tree.

2. From the project tree, drag an existing class, for example, an MBusinessDocument into the design panel.

TIBCO Designer creates a reference to MBusinessDocument and makes it the first union member.

3. Drag a second class, for example, an MAdvisoryDocument into the design panel.

TIBCO Designer creates a second class reference.

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 of type MBusinessDocument or MAdvisoryDocument .

You can add more than 2 class references as union members. You can also mix class references and other references.

Adding Sequence Reference Union Members

When you add a sequence union member to a union, TIBCO Designer creates a sequence reference. To define union members that are sequences, follow these steps:




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.

Adding Scalar Reference Union Members

When you add a scalar as a union member to a union, TIBCO Designer creates a scalar reference. To define union members that are scalars, follow these steps:


2. From the project tree, drag a scalar into the design panel. See Scalars on page 217.

TIBCO Designer creates a reference to the scalar.

3. From the project tree, drag a second scalar into the design panel.

TIBCO Designer creates a reference to the second scalar.

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

You can add more than 2 scalar references as union members. You can also mix scalar references and other references.

Adding Union Reference Union Members

When you add a union as a union member to an existing union, TIBCO Designer creates a union reference.

To define a union members that are, in turn, unions, follow these steps:

1. Select a Union in the project tree.

2. From the project tree, drag a union into the design panel. See Unions on page 218.

TIBCO Designer creates a reference to the union.



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.

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

1. Select the Sequence folder.

2. From the palette panel, drag a Generic Sequence into the design panel.

3. In the configuration panel, select the name, type of the elements, and length of the sequence.

The maximum length is the number of elements in the sequence.

AssociationsAn association has two endpoints and each association has attributes such as multiplicity and navigability.

Association TypesTo 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.



• CONSTRAINT_REF. An instance of class A and an instance of class B together contain enough key information to uniquely associate them with an instance of class C. Deletion of A or B instances should cause deletion of all C instances which are no longer referenced. The relation of A or B to C is of type CONSTRAINT_REF.

A Note on MultiplicityBoth 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 minMultiplicity and maxMultiplicity 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 minMultiplicity = 2 and maxMultiplicity = 4.

See any reference on UML for more details.


Schema Resource Reference | 223

Schema Resource Reference

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 ReferenceTIBCO 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 ReferenceTIBCO 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 ReferenceTIBCO 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 ReferenceTIBCO 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 ClassA 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.


Schema Resource Reference | 225

• 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 ScalarA 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 UnionA 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 SequenceA 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 FieldTIBCO 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 FieldTIBCO 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 FieldTIBCO 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 FieldTIBCO 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.


TIBCO Designer Adapter Schema Folders | 227

TIBCO Designer Adapter Schema Folders

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.

The following folders are discussed:

• Folder Resource

• AESchemas Folder

• Classes Folder

• Scalars Folder

• Unions Folder

• Sequences Folder

• Associations Folder

Folder ResourceFolder 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 AESchemas folder to organize Schema resources.

AESchemas FolderThe AESchemas 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.

Folders in the Generic Adapter Configuration point to this appendix (because they are folders, and online help for folders points here).

These folders are also discussed separately in Folder Reference on page 187.



Classes FolderThe 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 Scalars folder is a container for all scalars used by all applications in your project. It contains folders for scalars commonly used by applications.

• The Scalars folder under AESchemas/ae 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 Scalers folder under AESchemas is meant to hold a folder for the scalars used as schema by your application.

For more information, see Scalars on page 217

Unions FolderThe Unions 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 FolderThe Sequences 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 FolderThe Associations folder is a container for all associations used by all applications in your project. For more information, see Associations on page 221.


| 229

Chapter 5 Repository Palette

The Repository palette allows you to manipulate legacy project repositories and their data directly. You can also use this palette to interact with Administration Servers. In most cases, you interact with project repositories using the TIBCO Designer GUI elements. Using this palette is only useful in rare cases for legacy applications.

The Repository palette is therefore not displayed by default. To display the palette, choose Palettes > General > Repository from the TIBCO Designer menu bar. The palette is displayed if the check mark is visible.

Topics

• Introduction, page 230

• Managing Repository Instances, page 239

• Managing Repository Content, page 245

• Menus and Toolbar Icons, page 253

i You cannot use the Repository palette and associated Repository Finder to manage multi-file projects.


230 | Chapter 5 Repository Palette

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.

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

Projects and RepositoriesTIBCO Designer allows you to view and manipulate your data using two different paradigms:

• A project is a collection of information you are currently working on. A project represents the work you have done. You can save projects, share them with others, and open them again.

A project could contain, for example, several adapter instances used by your integration and folders to organize the adapters.

• A repository is a data store, that is, a collection of information stored in one place. Repositories can be simple, for example, contain data used by an application, or more complex, for example, contain the definitions for several adapters.

By default, the repository palette is hidden.

You can use Repository Finder only to manage 4.x repositories. It does not work for 5.x multi-file projects (VC format repositories).


Introduction | 231

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.

Showing the Repository PaletteBy default, the Repository palette is not displayed in the palette panel because its functionality is for repository management only.

To display the Repository palette, choose Palettes > General > Repository. That makes the Repository palette available from the palette panel when the top-level folder is selected.

Repository Finder ToolThe Repository Finder tool lets you locate and manage repositories.

• Locate both local and remote repositories based on the discovery criteria you specify. See Using Repository Finder to Locate Repositories, page 231.

• Manage repository instances. See Introduction on page 230.

• Stop a repository server. See Stopping a Repository Server, page 243.

• Manage data inside the repository. See Introduction on page 230.

When you add a Repository Finder to your project, the Finder is later saved as part of your project. However, the search information is not saved.

Using Repository Finder to Locate RepositoriesRepository Finder lets you locate both local and server-based 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 .dat format. You cannot locate repositories for multi-file projects.



To locate a repository, follow these steps:

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.

Drag a Repository Finder into the design panel.


Introduction | 233

Local FileRepositories

3. To locate local file repositories

a. Click the Local File Repositories tab.

b. Click the Search Locally check box.

c. Click Browse and select the directory in which the repository is located.

d. If you only want to look for local file repositories, click Rediscover.

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.

By default, Repository Finder only displays repository directories and objects. If you want to view attribute information, select Advanced Browsing in the Advanced tab before you click Rediscover. See Introduction on page 230.



Servers andInstances

4. Click Server Repositories if you want to find repository servers and their 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.

d. Click Rediscover (unless you intend to specify advanced settings).

TIBCO Designer finds any remote repositories for the specified TIBCO Rendezvous settings and displays them in the project tree.

If you do not have read permission for a server-based repository managed by TIBCO Administrator, you may not be able to display it.


Introduction | 235

5. Browse the local and remote repositories that match your search criteria. In the hierarchy, you see repository instances, directories, and objects.

6. If you need additional information on the contents of the object, or want to change its attribute, choose the Advanced tab, then turn on advanced browsing and editing. See Viewing Attributes of Repository Objects, page 249 and Modifying Attributes Inside Repository Objects, page 249.

Repository instance

Repository directory

Repository object

In most situations, adding resources to projects and manipulating their attributes is preferable to manipulating repository objects through the Repository Finder hierarchy. One reason for this is that TIBCO Designer makes sure the public and private repository areas are in sync if you edit a project, but cannot do so if you change a repository.



Navigating the Repository Hierarchy

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.

Servers and Instances

Here’s an example of the first level of the hierarchy which shows both local and server-based instances:

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 .dat file and accessed directly, not via TIBCO Rendezvous.

Repository server

Server-based instance

Local instance

You cannot view multi-file projects using Repository Finder.


Navigating the Repository Hierarchy | 237

Directories and Objects

When you go lower in the hierarchy, you see repository directories and objects.

See Repository Directory, page 238 and Repository Object, page 238 for more information.

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

Repository object

Repository Instance Repository Directory Repository Object



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.


Managing Repository Instances | 239

Managing Repository Instances

This section discusses the different repository management activities TIBCO Designer offers.

• Creating Repository Instances

• Specifying Additional Repository Information

• Cloning Repository Instances

• Deleting Repository Instances

• Stopping a Repository Server

• Starting or Stopping a Repository Instance

Creating Repository InstancesIn most circumstances, you do not create repository instances using the Repository Finder, but instead create a project and save it to the project repository. See TIBCO Designer User’s Guide, available via Help > Designer Help for more information.

If for some reason you want to create a repository using Repository Finder, you must first decide whether you want to create a local or a remote repository instance.

• Local repository files cannot be located by a repository server.

• Remote repositories can be files or in a database. They must always be associated with a repository server.

Creating Local Repository Instances

To create a local repository instance using Repository Finder, follow these steps:

1. If Local File Repositories is not currently displayed below Repository Finder in the project tree, find an already existing local repository instance.

TIBCO Designer displays a Local File Repositories icon in the project tree and below it any repository instances it found in the specified location.

Exporting and importing repositories is discussed in Introduction on page 230. It usually involves making changes to the XML file that results from the export.



2. Right-click Local Repositories and choose Create Repository Instance.

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

Creating a Repository Instance Managed by a Server

A repository instance managed by a server can be on any machine on the network, and can either be a file or inside a database.

To create a remote repository instance, follow these steps:

1. Make sure the repository server for the instance is running.

2. In the Repository Finder configuration panel, click Search Remotely, specify the search parameters for the server, and click Rediscover.

The server is displayed, even if this server currently has no instances.

3. From the right-button menu of the server, choose Create Repository Instance.

4. Provide the name, display name, and request subject prefix as prompted.

TIBCO Repository creates the repository instance in the remoteRepos directory associated with that server.

You can also add a repository instance by

— Selecting Local File Repositories.

— Dragging an Instance icon from the palette panel to the design panel.

— Specifying the instance information when prompted.



If you like, you can specify additional information. See Specifying Additional Repository Information on page 241.

Specifying Additional Repository InformationAfter you have created a local repository or a repository managed by a server, you can specify additional information for it as follows:

1. Select the repository.

2. In the configuration panel (with the General tab selected), specify the following information:

You can also add a repository instance by

— Selecting the appropriate repository server.

— Dragging an Instance icon from the palette panel to the design panel.

— Specifying the instance information when prompted.

Display Name

Display name for this repository

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

Responsible Person

Person to contact.

Description Description of this repository.

Support Info Support information for this repository.



The following information is included in the General tab but cannot be changed.

Cloning Repository InstancesYou can clone a repository instance, that is, create a precise copy that is associated with the same repository server as the original. To clone a repository instance, follow these steps:

1. In the project tree, right-click the repository instance you want to clone.

You can clone either a local or a remote repository.

2. Select Clone Repository Instance.

IsDefault If checked, this is the default repository.

Warning: There can be only one default repository within a repository network. That is then the repository to which the server connects when you search for repositories. The option should almost always be left unchecked.

Version Shows the version for this repository (cannot be changed). Default for TIBCO Designer 4.0.0 repositories is 4.0.0.

Instance Type

Either LocalFile for a local file repository or remoteRV for any repository managed by a server.

File Type Either BIN or XML, as specified during repository creation.

Dir Name (Local only) Directory in which this repository is stored.

Request Subject Prefix

TIBCO Rendezvous request subject prefix for this repository.



You are prompted for information about the new repository. For local file repositories:

3. Supply the information and click OK.

TIBCO Designer creates an exact copy of the source repository. If you clone a remote repository, the copy is accessible through the same server.

Deleting Repository InstancesTo delete a repository instance:

1. Select the instance.

2. From the right-button menu, choose Delete Repository Instance.

3. You are prompted whether you really want to delete the instance.

4. Click Yes to remove the repository, No to keep it where it is.

Stopping a Repository ServerYou can stop a repository server version 3.3 or later using TIBCO Designer as follows:

1. Select the repository server you want to stop.

2. From the right-button menu, click Stop Repository Server.

As an alternative, you can also click Stop Repository Server in the configuration panel’s General tab with the server selected.

Instance Name Name of the instance.

Display Name Display name.

File Type Either XML or BIN.

Dir Name Directory name for this repository.

Deletion is permanent. When deleting the instance, you are permanently removing it from the hard disk.

After you stop a repository server, no one on your network can view or modify repository instances associated with that server.



Starting or Stopping a Repository InstanceWhen you stop a repository instance, it is no longer visible to the server that manages it. As a result, it is also no longer visible through TIBCO Designer.

When you start a repository instance, it then becomes visible again.

To stop a repository instance, follow these steps:

1. Select the repository instance in the project tree.

2. From the right-button menu, choose Stop Repository Instance.

3. After a short time-out, the selected repository disappears from your display.

To start a repository instance, follow these steps:

1. Select the Repository Server for the repository instance.

2. From the right-button menu, choose Start Repository Instance.

3. Type the name of the repository into the dialog.

4. The repository is displayed below the selected server or below Local File Repositories.

You cannot start a repository that is already running.


Managing Repository Content | 245

Managing Repository Content

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 and Importing Repository InstancesTIBCO Designer functionality is in most cases sufficient and appropriate for making changes to a repository instance. In some cases, however, you may decide to export the repository to XML, make your changes, and import the file.

Exporting a repository instance means writing its contents to a TIBCO Repository XML file. Importing a repository means importing a file that was previously exported from TIBCO Repository into an existing repository.

During the import process, you have some control over rejecting or accepting import of duplicate repository directories or duplicate repository objects. You cannot control, however, whether a directory or object is imported that does not exist in the current repository instance. The RepoExport and RepoImport command line tools, available in <TIBCO_CORE_HOME>/tra/<version>/bin allow for more fine grained operations.

Exporting and importing are useful:

• For diagnostics and troubleshooting. Viewing the XML file may help you pinpoint a problem.

• For creating a copy of a repository instance in a different repository server.

• For merging local repository instances into one remote repository instance.

Exporting an Instance

To export a repository instance, follow these steps:

You can use the RepoImport and RepoExport command line tools instead of TIBCO Designer. These tools allow you to use schema validation as part of your export process if desired.



1. Select the repository instance.

2. From the right-button menu, choose Export Repository Instance.

3. Choose the location for the XML file, then click OK.

TIBCO Designer saves your repository to the specified location using TIBCO Repository XML format (generic format).

Importing an Instance

To import a repository instance, follow these steps:

1. Select a repository instance that you want to overwrite, or create a new repository and select it.

2. Right-click the repository and choose Import Repository Instance.

You are prompted for a file.

3. Select an XML file that had previously been exported from a repository, either using TIBCO Designer or using the RepoExport command-line utility.

The system prompts you with the following dialog:

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.

You can also use the Export icon to export a repository.



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.

Adding TIBCO Repository Directories and ObjectsIn almost all cases, you do not modify a repository directly. Instead, you modify a project, then save the project as a repository. In some situations, however, modifying the repository directly might be appropriate. You do so using the Repository palette.

To add a directory and an object to a repository, follow these steps:

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.

Advanced Repository ManagementThe Advanced tab specifies information for both local and remote repositories.

You can also use the Import icon to import a repository.

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:

1. Drag a Repository Finder into the design panel.

2. With the Repository Finder selected, click the Advanced tab in the configuration panel.

User Name of the user that accesses the repository. The repository needs this information for keeping track of who currently uses a repository.

Password Password to access the repository. This might be needed if the repository is stored in a database.

Advanced Browsing If checked, you can view attribute and property information. The default, unchecked, is usually appropriate because low-level work should be done using the project view.

Advanced Editing If checked, you can edit attribute and property information. The default, unchecked, is usually appropriate because low-level work should be done using the project view.



Viewing Attributes of Repository ObjectsYou can use repository finder to view the contents of repository objects. Follow these steps:

1. Turn on Advanced Browsing.

2. Select an object you want to view.

3. Click the Advanced tab in the configuration panel.

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 statusMsg has an attributeType that is a global name.

Modifying Attributes Inside Repository ObjectsThis section explains how to modify attributes of repository objects.

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, attributeType , and isKey are properties of the attribute. Custom properties are also allowed.

Object

Attribute

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.



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 defaultStartup property of the startup attribute is being edited.



6. If you want to add a new association list to an object or an association list, or add a property to an association list, use one of the following icons (see Table 16 for explanation):

Table 16 Icons in Extended Properties Editor

Icon Description

Association list icon

Click to add an association list below the current location.

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

File => byte array Loads a file into a byte array.

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.

Reference Icon Add a reference to another object inside the repository. You can use this, for example, to point to a session you created in the public area of the project. The patch always starts with /tibco , for example, /tibco/public/session/.../mySession.

association list

binary

reference

string

up/downdelete

save the value of a binary property

load file into a byte array (file => byte array)

into a file (byte array => file)



You can also move properties by clicking the up/down icon, and delete them by clicking the delete icon.

String Adds a string property to the current association list.

Table 16 Icons in Extended Properties Editor

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.


Menus and Toolbar Icons | 253

Menus and Toolbar Icons

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.

• Repository Server Menu

• Repository Instance Menu

• Toolbar Icons

Repository Server MenuWhen you select a Repository Server or the Local File Repositories icon, the following items become available:

Repository Instance MenuWhen you select a repository instance, the following menu items become available:

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.

What is this Displays online help.

Create Repository Instance

Prompts you for information about the repository instance you wish to create. See Creating Repository Instances on page 239.

Start Repository Instance

Prompts you for the name of an instance to start. (Not available from Local File Repositories icon).

Stop Repository Server

Stops the selected (Not available from Local File Repositories icon).

Add Resource Allows you to add repository instances.

What is this Displays online help.



Toolbar IconsWhen 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.

Stop Repository Instance

Stops this repository instance so it is no longer visible as one of the instances of this server.

(Only available for server-based repositories).

Clone Repository Instance

Clones a repository instance. See Cloning Repository Instances, page 242.

Export Repository Instance

Exports a repository instance. See Exporting an Instance, page 245.

Import Repository Instance

Imports a repository instance. See Importing an Instance, page 246.

Delete Repository Instance

Deletes a repository instance. See Deleting Repository Instances, page 243.

Add Resource Adds a resource to the instance.

Export to XML File—Exports the selected instance to a TIBCO Repository XML file. Clicking this button does the same things as using the TIBCO Repository RepoExport command-line tool.

The file is saved in generic XML format (not AEXML format).

Import file into Repository—Displays a window that lets you choose an XML file to import into the currently selected repository instance. You can import repositories in generic or AEXML format.

Clone selected Repository—Creates a copy of the selected repository.


| 255

Index

A

adapter endpoints 205adapter schemas palette 208adapters

configuring 203creating 145

Add Module button 102Add Namespace button 55adding 15adding adapters 145adding class fields 210adding class union members 219adding color to tags 129adding new XML resource 15adding operations 212adding scalar union members 220adding sequence union members 220adding unions as union members 219Advanced folder 188Advanced pane

Notations tab 65Advanced panel 63, 103advanced repository management 247advisories 186Advisories folder 190aliases for attributes 129aliases for elements 129all content models 36all occurrence indicators 35appendmode attribute 171association lists 249associations 221

types 222

attributes 38, 149, 209, 249adding 209aliases 129declaring 51hiding 128inserting 122promoted 130

Attributes panel 50, 93

B

blue ellipsis icon 135building content model

with reusables 91building content models

content model editor 49, 91occurrence and sequence indicators 45, 87

building documents 138

C

choice 34class 209, 212

adding attributes 209class fields 210class reference 219client service 164clients 196cloning repository instances 242cmname attribute 177cmqname attribute 178collapsing elements 128collapsing markup view 135color

adding to tags 129


256 | Index

color options 129comments 124

inserting 122common table columns 26, 27completed content model 46Configuration panel 38, 82, 120Configuration tab 156configuring standard adapters 203Constraints tab 61content hints 132

as tool tip 125content model

diagram 33, 49editor 49, 91example 46, 89specifying data type 36

Content model diagram 36content model diagram 33, 93

modifying display 36navigating 36

content model editor 49, 91content panel 121, 138

edit area 131tag area 122

control poolsJDBC 184MTS 186Null 185ODBC 185XA 186

creating internal parameter entities 104creating local repository instances 239creating repository instances 239, 240custom adapters 204custom log sinks 147customer support xviicustomized view tag area 126customizing documents 139

D

daemon attribute 175, 176, 178, 179

data typecreating 66specifying in content model panel 36

data types panel 66declaring attributes 51defaulttimelimit attribute 177defining external general entities 107defining external unparsed entities 107defining internal general entities 106deleting items 149deleting repository instances 243directories 237, 247document-building options 139documents

customizing 139modifying structure 124navigating 125populating 139

DTD 82DTD example, examples

DTD 113

E

element list 84element/type list 41element/types list 41elements

aliases 129collapsing 128expanding 128hiding s 128inserting 122promoted 130

elements panel list 84elements/types list 40endpoints 205

overview 191entry constraints 125enumeration tab 62, 103

Properties pane 103Errors panel 110, 135


Index | 257

examplebuilding simple schema 70defining and deriving complex and simple types 76

examplesbuilding a content model 46, 88creating a schema 18creating a user-derived data type 67creating or editing an attribute 51, 98including declarations from another schema 57, 102referencing an element from another namespace 55

exception parameters 217exceptions folder 215expanding elements 128expanding markup view 135exporting and importing repository instances 245exporting instances 245exporting repository instances 243, 245exporting to XML 254external general entity 106, 107external parameter entities 105external unparsed entity 107

F

factory bar 123fields

type class 210type scalar 211type sequence 211type union 211

file sink 171folders

Advanced 188Advisories 190Log Sinks 189

G

general entities 106general entity 105, 106, 107generic adapter configuration 145

getting startedinstance resources 21schema and DTD resources 17XML tools palette 15

graphical viewschema 75, 117

H

hawk sink 173hiding attributes 128hiding elements 128

I

identifying dataentry constraints 125

importing an instance 246importing namespace 55importing repository instances 243, 245importing XML files 254Insert box 122, 123inserting

attributes 122elements 122

inserting comments 122, 124inserting processing instructions 122instance 119instance editing environment 22instance resources

getting started 21internal general entities 106internal general entity 106internal parameter entities 91internal parameter entity 104introduction to XML 14item right-button menu 127


258 | Index

J

JDBC control pool 184

L

ledgerfile attribute 177legacy adapters 204Load URL 190local instance 236local repository instances 239locating repositories 231log sinks

custom 147folder 189overview 170

logging tab 156

M

markup format 134markup view

collapsing 135expanding 135

menu options 28metadata 237mixed content model 35modifying attributes 249modifying display of content model diagram 36modifying document structure 124monitoring tab 158MTS control pool 186multiplicity 222

N

namespace 55Namespaces tab 63navigating content model diagram 36

navigating the document 125Navigator bar 125network attribute 175, 176, 178, 179network sink 172new data type 66new resource 15Notations tab 64

Advanced pane 65Notes panel 68, 110null control pool 185

O

objects 237, 247occurrence indicators 35, 45, 87ODBC control pool 185operation exceptions folder 215operation parameter folder 214operation parameters 214operations 212, 213

defining 214exception parameters 217parameters 214

optional and repeatable set of choices 35Overview panel 53, 100Overview tree 54, 101overwriting traces 171

P

panels 24Parameter entities tab 104parameter folder 214parameters

type class 215type scalar 216type sequence 215type union 216

populating documents 139processing instructions 109

inserting 122


Index | 259

projects 230promoted attributes 130promoted elements 130properties 149Properties pane

enumeration tab 103Properties panel 58, 102Properties tab 58publisher services 160publishers

default time limit 177, 180

R

reading the content model diagram 33referencing complex types in other schemas 81referencing elements from another namespace 56referencing parameter entities within a content

mode 104referencing reusable (internal) parameter entities 92repositories 230repository directories 247repository directory 238repository finder 231repository instance 237repository instances

cloning 242creating 239, 240exporting 243, 245importing 243, 245locating 231starting 244stopping 244

repository management 247repository object 238repository objects 247

viewing 249repository palette 237repository server 236repository servers

locating 231stopping 243

request-response invocation service 164

request-response server 167requireoldmessages attribute 177resizing rows to allow for additional promotion 131resource

creating 15reviewing schema 75, 117right-button menu 124row format (default view) 134RPC class 212rv publisher 192rv session 175rv tx publisher 194rva session 175rvcm publisher 193rvcm session 176rvcm sessions

defaultTimeLimit attribute 177ledger files 177rvCmSession attribute 177

rvcmq session 177rvtx session 180

S

scalar fields 211scalar reference 220scalars 217scheduleractivation attribute 179schedulerheartbeat attribute 178schedulerweight attribute 178schema 37

graphical view 75, 117reviewing 75, 117

schema and DTD resourcesgetting started 17

Schema menu 40, 83schema and DTD resources 28

Schema properties panel 68, 110


260 | Index

schemasand tibco designer 205basics 203example 206folder 208overview 203

selecting a hidden element to show 128sequence 34sequence fields 211sequence indicators 45, 87sequence reference 220sequences 221server service 167server-based instance 236servers 198

stopping 243servers and instances 236service attribute 175, 176, 178, 179services

client 164publisher 160request-response 167request-response invocation 164server 167subscriber 162

sessions 145sessions folder 189setting a schema 120Show as markup 134Show as Rows 134siblings displayed on navigator bar 126simple control pool 186sinks

file sink 171hawk sink 173

Source panel 69, 112, 136Source view 76, 117specifying additional repository information 241specifying an alias 129specifying data type in content model panel 36specifying values for existing properties 149standard adapter endpoints 205standard adapters 203starting repository instances 244startup tab 157

statistics 38, 82stdio sink 172stopping repository instances 244stopping repository servers 243subscriber service 162subscribers 196support, contacting xvii

T

tag areacustomized view 126

tagsadding color 129

technical support xviiterminology 148, 249TIBCO Rendezvous 237timer 199timers folder 189toolbar 40, 83, 120toolbar buttons 27traces

maximum file size 171number of rollover files 171overwrite vs. append 171

transaction controls 184transaction controls folder 189type right-button menu 127

U

unacknowledged messages 177understanding file count and file limit 171union fields 211union members 219, 220union reference 219unions 218, 219unparsed entity 107


Index | 261

V

viewing attributes 249

X

XA control pool 186XML

introduction 14XML file 254XML instance editing environment 119XML instance exercise 137XML menu 120XML menu (instance resources) 30XML resource 15XML schema exercises 70XML tools palette

getting started 15XML tools palette resources

common table columns 27


262 | Index


tibco designer palettes

Documents

trademarks of tibco

bundled tibco software

licensed tibco software

tibco rendezvous

tibco repository

tibco administrator

tibco adapter

bundled software