Está en la página 1de 304

Configuration and Management Guide

V7.6

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
2008 Progress Software Corporation. All rights reserved.
Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. This manual is also
copyrighted and all rights are reserved. This manual may not, in whole or in part, be copied, photocopied, translated, or reduced to
any electronic medium or machine-readable form without prior consent, in writing, from Progress Software Corporation.
The information in this manual is subject to change without notice, and Progress Software Corporation assumes no responsibility for
any errors that may appear in this document.
The references in this manual to specific platforms supported are subject to change.
A (and design), Actional, Actional (and design), Affinities Server, Allegrix, Allegrix (and design), Apama, Business Empowerment,
ClientBuilder, ClientSoft, ClientSoft (and Design), Clientsoft.com, DataDirect (and design), DataDirect Connect, DataDirect
Connect64, DataDirect Connect OLE DB, DataDirect Technologies, DataDirect XQuery, DataXtend, Dynamic Routing
Architecture, EasyAsk, EdgeXtend, Empowerment Center, Fathom, IntelliStream, Neon, Neon New Era of Networks, O (and
design), ObjectStore, OpenEdge, PeerDirect, Persistence, POSSENET, Powered by Progress, PowerTier, ProCare, Progress,
Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment Center, Progress Empowerment
Program, Progress Fast Track, Progress OpenEdge, Progress Profiles, Progress Results, Progress Software Developers Network,
ProVision, PS Select, SequeLink, Shadow, ShadowDirect, Shadow Interface, Shadow Web Interface, ShadowWeb Server, Shadow
TLS, SOAPStation, Sonic ESB, SonicMQ, Sonic Orchestration Server, Sonic Software (and design), SonicSynergy, SpeedScript,
Stylus Studio, Technical Empowerment, Voice of Experience, WebSpeed, and Your Software, Our Technology-Experience the
Connection are registered trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and/or other
countries. AccelEvent, Apama Dashboard Studio, Apama Event Manager, Apama Event Modeler, Apama Event Store, AppsAlive,
AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Cache-Forward, DataDirect Spy, DataDirect SupportLink, DataDirect XML
Converters, Future Proof, Ghost Agents, GVAC, Looking Glass, ObjectCache, ObjectStore Inspector, ObjectStore Performance
Expert, Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress
RFID, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView,
SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Sonic, Sonic
Business Integration Suite, Sonic Process Manager, Sonic Collaboration Server, Sonic Continuous Availability Architecture, Sonic
Database Service, Sonic Workbench, Sonic XML Server, The Brains Behind BAM, WebClient, and Who Makes Progress are
trademarks or service marks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries.
Vermont Views is a registered trademark of Vermont Creative Software in the U.S. and other countries. IBM is a registered trademark
of IBM Corporation. JMX and JMX-based marks and Java and all Java-based marks are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries. Any other trademarks or service marks contained herein are the property of their
respective owners.
Third Party Acknowledgements:
SonicMQ and Sonic ESB Product Families include code licensed from RSA Security, Inc. Some portions licensed from IBM are
available at http://oss.software.ibm.com/icu4j/.
SonicMQ and Sonic ESB Product Families include the JMX Technology from Sun Microsystems, Inc. Use and Distribution is subject
to the Sun Community Source License available at http://sun.com/software/communitysource.
SonicMQ and Sonic ESB Product Families include software developed by the ModelObjects Group (http://www.modelobjects.com).
Copyright 2000-2001 ModelObjects Group. All rights reserved. The name "ModelObjects" must not be used to endorse or promote
products derived from this software without prior written permission. Products derived from this software may not be called
"ModelObjects", nor may "ModelObjects" appear in their name, without prior written permission. For written permission, please
contact djacobs@modelobjects.com.

SonicMQ and Sonic ESB Product Families include files that are subject to the Netscape Public License Version 1.1 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.mozilla.org/NPL/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY
OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the
License. The Original Code is Mozilla Communicator client code, released March 31, 1998. The Initial Developer of the Original
Code is Netscape Communications Corporation. Portions created by Netscape are Copyright 1998-1999 Netscape Communications
Corporation. All Rights Reserved.
SonicMQ and Sonic ESB Product Families include versions 8.3 and 8.9 of the Saxon XSLT and XQuery Processor from Saxonica
Limited (http://www.saxonica.com/) which is available from SourceForge (http://sourceforge.net/projects/saxon/). The Original
Code of Saxon comprises all those components which are not explicitly attributed to other parties. The Initial Developer of the
Original Code is Michael Kay. Until February 2001 Michael Kay was an employee of International Computers Limited (now part of
Fujitsu Limited), and original code developed during that time was released under this license by permission from International
Computers Limited. From February 2001 until February 2004 Michael Kay was an employee of Software AG, and code developed
during that time was released under this license by permission from Software AG, acting as a "Contributor". Subsequent code has been
developed by Saxonica Limited, of which Michael Kay is a Director, again acting as a "Contributor". A small number of modules, or
enhancements to modules, have been developed by other individuals (either written specially for Saxon, or incorporated into Saxon
having initially been released as part of another open source product). Such contributions are acknowledged individually in comments
attached to the relevant code modules. All Rights Reserved. The contents of the Saxon files are subject to the Mozilla Public License
Version 1.0 (the "License"); you may not use these files except in compliance with the License. You may obtain a copy of the License
at http://www.mozilla.org/MPL/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY
OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the
License.
SonicMQ and Sonic ESB Product Families include software developed by IBM. Copyright 1995-2002 and 1995-2003 International
Business Machines Corporation and others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies
of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS
INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL
DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder
shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written
authorization of the copyright holder.

SonicMQ and Sonic ESB Product Families include software Copyright 1999 CERN - European Organization for Nuclear Research.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in
supporting documentation. CERN makes no representations about the suitability of this software for any purpose. It is provided "as
is" without expressed or implied warranty.
SonicMQ and Sonic ESB Product Families includes software developed by the University Corporation for Advanced Internet
Development <http://www.ucaid.edu>Internet2 Project. Copyright 2002 University Corporation for Advanced Internet
Development, Inc. All rights reserved. Neither the name of OpenSAML nor the names of its contributors, nor Internet2, nor the
University Corporation for Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote products derived
from this software and products derived from this software may not be called OpenSAML, Internet2, UCAID, or the University
Corporation for Advanced Internet Development, nor may OpenSAML appear in their name without prior written permission of the
University Corporation for Advanced Internet Development. For written permission, please contact opensaml@opensaml.org.
Portions of SonicMQ and Sonic ESB Product Families were created using JThreads/C++ by Object Oriented Concepts, Inc.
SonicMQ and Sonic ESB Product Families were developed using ANTLR
SonicMQ and Sonic ESB Product Families include software Copyright 1991-2007 DataDirect Technologies Corp. All rights
reserved. This product includes DataDirect products for the Microsoft SQL Server database which contain a licensed implementation
of the Microsoft TDS Protocol.
SonicMQ and Sonic ESB Product Families include software developed by the OpenSSL Project for use in the OpenSSL Toolkit
(http://www.openssl.org/). Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved. This product includes cryptographic
software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved. The names "OpenSSL Toolkit" and "OpenSSL
Project" must not be used to endorse or promote products derived from this software without prior written permission. For written
permission, please contact openssl-core@openssl.org. Products derived from this software may not be called "OpenSSL" nor may
"OpenSSL" appear in their names without prior written permission of the OpenSSL Project. Software distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and
limitations under the License agreement that accompanies the product.

February 2008

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Progress Sonic ESB Product Family Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11
12
13
14
15

Part I: ESB Configuration Tools and Managed Components


Chapter 1: Using Progress Sonic ESB
Configuration and Management Tools19
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sonic Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESB Configured Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESB Admin Tool and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SonicFS Maintenance Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESB Type Maintenance Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
License Container Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Management Container Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deployment Tool Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shutting Down Sonic Components and Sonic ESB Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

20
21
26
33
34
35
37
39
39
40
47

Contents

Chapter 2: ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Creating ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
ESB Container Intra-container Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Viewing or Editing ESB Container Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Managing the Services Associated with an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Adding Services or ESB Process Entry Points to an ESB Container . . . . . . . . . . . . . . . . . . . . .59
Deleting ESB ContainerServices from an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Changing the Number of Listeners on Services in ESB Containers . . . . . . . . . . . . . . . . . . . . .61
Deploying an ESB Container in a Management Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Setting Test Mode for ESB Containers Used in Development. . . . . . . . . . . . . . . . . . . . . . . . . .62
Adding JAR files to an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Changing the State of Management and ESB Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Monitoring Service Metrics and Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Standard Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Standard Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Enabling Integration with Actional for Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Using Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Creating an Activation Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Adding an Activation Daemon to a Management Container . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Adding an ESB Container to an Activation Daemons Activation List . . . . . . . . . . . . . . . . . . .81

Chapter 3: ESB Endpoints and Connections. . . . . . . . . . . . . . . . . . . . . . . . . . .83


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
ESB Addresses and References to Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Entry Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Exit Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Fault Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Rejected Message Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Evaluating Endpoint Requirements on JMS Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
When to Use Topics, When to Use Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Multiple Brokers, Clusters, and Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Configuring Progress SonicMQ Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Deleting Progress SonicMQ Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Fault Tolerant Connections and Reconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Inbound and Outbound Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Fault Tolerant Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Setting the Ping Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
6

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Contents

Configuring Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103


Deleting Progress SonicMQ Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 4: Configuring Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

111
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Configuring WebService Protocols for ESB Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Related Configuration Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Part II:

Configuring XML Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 5: Monitoring and Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6: Performance Tuning XML Servers . . . . . . . . . . . . . . . . . . . . . . . .


Tools for Tuning XML Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Properties on an XML Service Type Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Properties on a Component in an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting JVM System Properties on a Management Container . . . . . . . . . . . . . . . . . . . . . . . .
Tuning XML Services and Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transactions and Concurrency Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Action Flows, Transactions, and XML Services . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning XML Service Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distributing Documents in Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locations for Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Storage Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing the Transaction Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPath Expressions and XSLT Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPath Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLT Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

117
118
118
121
123
125
126
127
128
129
130
130
132
136
139
140
140
141
143
144
145
146
146
148

Contents

Chapter 7: Backing Up and Restoring Document Collections . . . . . .151


Backing Up Sonic XML Server Document Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Designing a Backup Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Files Generated by the Backup and Restore Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Using the Backup Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Performing Full Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Performing Incremental Backup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Restoring Sonic XML Server Document Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Using the Restore Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Restoring from Full Backup Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Restoring from Incremental Backup Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Part III:

Configuring Database Services . . . . . . . . . . . . . . . . . . . . .163

Chapter 8: Using the Database Service JDBC Drivers . . . . . . . . . . . . . . .165


JDBC Driver Connection Properties and the Database Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Load Balancing, Failover, and Connection Retry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Client Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Connection Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Connection Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Specifying Primary and Alternate Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Using Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Chapter 9: Driver Connection Properties and Data Types by Database Brand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Progress OpenEdge Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Progress OpenEdge Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Progress OpenEdge Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
Specifying Alternate Servers for the Progress OpenEdge Driver . . . . . . . . . . . . . . . . . . . . . .182
Progress OpenEdge Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
DB2 Driver Connection Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
DB2 Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Specifying Alternate Servers for the DB2 Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
DB2 Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Informix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Informix Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Informix Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
8

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Contents

Specifying Alternate Servers for the Informix Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


Informix Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Alternate Servers for the Oracle Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server Driver Connection Failover Properties. . . . . . . . . . . . . . . . . . . . . . . .
Specifying Alternate Servers for the Microsoft SQL Server Driver . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Alternate Servers for the Sybase Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase Driver Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

209
210
212
212
223
224
225
227
227
238
238
240
242
242
252
252
254

Chapter 10: SQL Escape Sequences for JDBC

257
258
258
265
266

......................
Date, Time, and Timestamp Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scalar Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outer Join Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Procedure Call Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 11: Configuring SQL Server Windows Authentication . . . .

267
Setting the Authentication Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Registering Service Principal Names (SPNs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Setting the Active Directory Encryption Property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Contents

Part IV:

Configuring and Managing BPEL Services . . . . . .271

Chapter 12: Configuring BPEL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273


Overview of BPEL Service Initialization Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Specifying a BPEL Archive (.bpar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Setting Persistence Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
BPEL Development Container Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Enabling Audit Trails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Audit Trails and Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
Setting a Default Partner Link. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Considerations with Dehydrated Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285

Chapter 13: Managing BPEL Services

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Overview of BPEL Service and Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Clearing Process History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Terminating Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
Searching for Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
Viewing Audit Trails. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
BPEL Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10

297

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Preface

This Preface contains the following sections:

About This Guide describes this manual and its intended audience.

Typographical Conventions describes the text formatting, syntax notation, and


flags used in this manual.

Progress Sonic ESB Product Family Documentation describes the books and API
online references packaged with the Sonic ESB Product Family.

Worldwide Technical Support provides information on how to contact Progress


Softwares customer support and evaluation support for the Progress Sonic ESB
Product Family.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

11

Preface

About This Guide


This guide is intended for system administrators. This book is in four parts:

Part I, ESB Configuration Tools and Managed Components, includes the chapters:

Chapter 1, Using Progress Sonic ESB Configuration and Management Tools


introduces Progress Sonic ESB and its configuration and management tools.

Chapter 2, ESB Containers describes ESB Containers and Activation


Daemons.

Chapter 3, ESB Endpoints and Connections describes how to use ESB


components and resources.

Chapter 4, Configuring Web Services describes using Web Service standards in


the configuration and management of ESB components and resources.

Part II, Configuring XML Servers, includes the chapters:

Chapter 5, Monitoring and Logging, describes Progress Sonic XML Server


metrics, notifications, and logging.

Chapter 6, Performance Tuning XML Servers, includes suggestions to


optimize XML Server configuration and application design.

Chapter 7, Backing Up and Restoring Document Collections, describes how to


backup and restore Progress Sonic XML Server document collections.

Part III, Configuring Database Services, includes the chapters:

Chapter 8, Using the Database Service JDBC Drivers, explains how to


configure load balancing, failover, and connection retry for connections made
using the drivers.

Chapter 9, Driver Connection Properties and Data Types by Database Brand,


describes the properties and data types for several database brands: Progress
OpenEdge, DB2, Informix, Oracle, Microsft SQL Server, and Sybase.

Chapter 10, SQL Escape Sequences for JDBC, describes the JDBC-defined
escape sequences containing standard syntaxes for several language features.

Chapter 11, Configuring SQL Server Windows Authentication, describes how


to use Windows authentication on Microsoft SQL Server with the Progress Sonic
Database Service JDBC SQL Server driver.

Part IV, Configuring and Managing BPEL Services, includes the chapters:

Chapter 12, Configuring BPEL Services, explains how to configure configure


BPEL services.

Chapter 13, Managing BPEL Services, describes how to manage BPEL


services.
12

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Typographical Conventions

Typographical Conventions
This section describes the text formatting conventions used in this guide and a description
of notes, warnings, and important messages. This guide uses the following typographical
conventions:

Bold typeface in this font indicates keyboard key names (such as Tab or Enter) and
the names of windows, menu commands, buttons, and other Sonic user interface
elements. For example, From the File menu, choose Open.

Bold typeface in this font emphasizes new terms when they are introduced.

Monospace typeface indicates text that might appear on a computer screen other than
the names of Sonic user-interface elements, including:

Code examples and code that the user must enter

System output such as responses and error messages

Filenames, pathnames, and software component names, such as method names

Bold monospace typeface emphasizes text that would otherwise appear in monospace
typeface to emphasize some computer input or output in context.

Monospace typeface in italics or Bold monospace typeface in italics (depending


on context) indicates variables or placeholders for values you supply or that might
vary from one case to another.
This guide uses the following syntax notation conventions:

Brackets ([ ]) in syntax statements indicate parameters that are optional.

Braces ({ }) indicate that one (and only one) of the enclosed items is required. A
vertical bar (|) separates the alternative selections.

Ellipses (...) indicate that you can choose one or more of the preceding items.
This guide highlights special kinds of information by shading the information area, and
indicating the type of alert in the left margin.
Note Note indicates information that complements the main text flow. Such information is

especially important for understanding the concept or procedure being discussed.


Important Important indicates information that must be acted upon within the given context in order

for the procedure or task (or other) to be successfully completed.


Warning Warning indicates information that can cause loss of data or other damage if ignored.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

13

Preface

Progress Sonic ESB Product Family Documentation


The Sonic ESB Product Family provides the following documentation:

Introducing the Progress Sonic ESB Product Family Introduces components of the
Sonic ESB Product FamilySonic ESB, Sonic Database Service, Sonic XML
Server, and Sonic BPEL Server.

Progress Sonic ESB Product Family: Installation and Upgrade Guide Provides
information about installing, updating, and upgrading Sonic ESB components.

Progress Sonic ESB Product Family: Developers Guide (Progress Sonic Workbench
Online Help) Provides information about developing, testing, and debugging
applications on the Progress Sonic Workbench. Describes the Sonic Workbench, its
editors, and tools. Provides information about how to get started with each component
of the Sonic ESB Product Family and describes sample applications.

Progress Sonic ESB Product Family: Configuration and Management Guide


Provides information about configuring and managing components used by the Sonic
ESB Product Family. Describes deployment configurations for Sonic ESB, Sonic
Database Service, Sonic XML Server, and Sonic BPEL Server

Progress Sonic ESB Product Family: Deployment Guide Provides information


about moving development projects into test and production environments. Describes
recommended build procedures, domain mappings, and reporting features.

Progress Sonic BPEL Server: Management API Guide Describes how to use the
management API to programatically access BPEL server functionality.

Sonic ESB API Reference Online JavaDoc compilation of the Sonic ESB APIs.

14

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Worldwide Technical Support

Worldwide Technical Support


Progress Softwares Sonic support staff can provide assistance from the resources on their
Web site at www.progress.com/sonic. There you can access technical support for licensed
Progress Sonic editions to help you resolve technical problems that you encounter when
installing or using Sonic SOA products.
When contacting Technical Support, please provide the following information:

The release version number and serial number of SonicMQ that you are using. This
information is listed on the license addendum. It is also at the top of the SonicMQ
Broker console window and might appear as follows:
SonicMQ Continuous Availability Edition [Serial Number nnnnnnn]
Release nnn Build Number nnn Protocol nnn

The release version number and serial number of Sonic ESB that you are using. This
information is listed on the license addendum. It is also near the top of the console
window for a Sonic ESB Container. For example:
Sonic ESB Fault Tolerant Edition [Serial Number: nnnnnnn]
Release nnn Build Number nnn

You can alternatively access version information programmatically for installed


Sonic components using the Version class in the Sonic API. See the Upgrading
Sonic ESB Product Family Components chapter in Progress Sonic ESB Product
Family: Installation and Upgrade Guide for instructions.

Note

The platform on which you are running Progress Sonic ESB Product Family products,
and any other relevant environment information.
The Java Virtual Machine (JVM) your installation uses.
Your name and, if applicable, your company name.
E-mail address, telephone, and fax numbers for contacting you.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

15

Preface

16

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Part I

ESB Configuration Tools


and Managed Components

Part I contains the following chapters:

Chapter 1, Using Progress Sonic ESB Configuration and Management Tools

Chapter 2, ESB Containers

Chapter 3, ESB Endpoints and Connections

Chapter 4, Configuring Web Services

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

17

18

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 1

Using Progress Sonic ESB Configuration


and Management Tools

Chapter 1 describes the tools for configuring and managing the Progress Sonic ESB
product family:

Overview describes how and where the Sonic ESB tools are used.

Sonic Management Console introduces this tool for managing and monitoring
components deployed in containers, including ESB Containers and Progress
SonicMQ brokers. This section also describes the ESB Configured Objects section,
used for configuring components such as ESB Containers, endpoints, services, and
ESB processes, and deploying them in an ESB Container.

ESB Admin Tool and Commands introduces this tool for command line actions that
configure Progress Sonic ESB containers and components, and manage the lifecycle
of Progress Sonic ESB components in management containers.
For information about the Sonic ESB developmemt environment, see the Progress Sonic
ESB Product Family: Deployment Guide in the Sonic Workbenchs Eclipse help.
Important This book assumes that you have deployment installations of Progress Sonic V7.6

products. While the Sonic Workbench has the same toolset, Sonics integration of the
tools into the development environment precludes direct access to these tools. As such, if
you are using the Sonic Workbench, you might find some Start menu commands and
some screenshots in this chapter inconsistent with those in a Workbench installation. You
should avoid manipulating files that support a Sonic Workbench in its Directory Service
unless explicitly instructed to do so, as you could cause unpredictable behavior in your
SonicWorkbench.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

19

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

Overview
The tools provided for configuring and managing Sonic ESB are independent of any
Sonic domain. The tools are typically installed on systems where runtime components
will not run. They connect to domains over the internet protocols to connect to a
management broker for a domain for viewing and maintaining the configuraton objects in
that domain. As a result, administrators can disconnect, relocate, and reconnect to diverse,
distributed domains whenever and wherever needed.
Whats a Sonic domain? A Sonic domain is an administrative grouping of Progress

Sonic management containers, and brokers administered by one central management


node, its Domain Manager. The domain manager is defined by its components:

A management container that provides caching facilities, communicates with its


management node (the broker it hosts), and hosts the other components of the domain
manager.

A broker dedicated to management communications for the domain managers two


essential functions, the Directory Service and the Agent Manager.

A Directory Service that provides a centralized point for configuration information,


runtime management, and configuration storage.

An Agent Manager that monitors the state of all management containers in the
domain.
For information about the domain manager, see the Introduction to Configuration
chapter in the Progress SonicMQ Configuration and Management Guide and the
Distributing Components chapter in the Progress SonicMQ Deployment Guide.
To use the Sonic ESB configuration and management tools, you must have a domain
manager installed and the administration tools for SonicMQ and Sonic ESB installed. See
the Progress Sonic ESB Product Family: Installation and Upgrade Guide for information
on a variety of installations of these product features.
Once the software is installed and acessible, the first step is to start the domain manager.
To start a domain manager:

On Windows, choose:
Start > Programs > Progress > Sonic 7.6 > Start Domain Manager

20

On UNIX or Linux, set a console window to the Progress SonicMQ installation


directory, and type ./bin/startcontainer.sh and press Return.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sonic Management Console

Sonic Management Console


The Sonic Management Console (SMC) provides a graphic interface for configuring,
managing, and monitoring configureed objects in the Sonic domain as well as launching
supporting tools.
To start the Sonic Management Console:

On Windows, choose:
Start > Programs > Progress > Sonic 7.6 > Sonic Management Console

On UNIX or Linux, set a console window to the Progress SonicMQ installation


directory, and type ./bin/startmc.sh and press Return.
The Sonic Management Console opens. The Create Connection dialog box opens, as
shown:

A Connection Name, the Domain Name, and its Connection URL are required when
security is not enabled on the management broker. When security is enabled on the
management broker, an authentic User Name and Password are also required. The
dialog box displays all the default values except the default users password:
Administrator.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

21

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools


To connect the Management Console to the domain:
1.

Enter the connection information for the domain:


Property

Description

Connection Name

Identity to be associated with this connection.

Domain Name

Name of the domain.

Connection URL(s)

URL(s) of the management broker(s).

User Name

The user name for connection.

Password

The password of the user.

For information about using the Advanced settings, see the Sonic Management
Console chapter in the Progress SonicMQ Configuration and Management Guide.
2.

22

Click OK. A Connecting... dialog box and the status bar indicate that the Sonic
Management Console is connecting to the management broker for a domain.
The Sonic Management Console opens a connection window to the domain, and
shows its objects in the Configure view. The following example shows the ESB
Containers folder selected:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sonic Management Console


3.

In the left panel, expand System > DBService > 7.6 > lib:

These are the supporting files for the configuration objects. They are accessed
through the Sonic File System, SonicFS. Sonic ESB Containers and Sonic
Workbench use the sonicfs protocol to reference files in SonicFS, for example,
sonicfs:///System/DBService/7.6/lib/ssoracle.jar.
The Resources folder stores files you create and that you will reference by
connecting to the domain manager where they are stored and using the syntax
sonicfs:///Resources/myFile. A resource is the term used for a file in SonicFS used
by Progress Sonic ESB components. Resources are referenced in parameters for
services, ESB processes, endpoints, and connections. Resource files can be accessed
from SonicFS. For example, a service can read a script file directly from SonicFS.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

23

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools


4.

Select the Manage tab and expand Containers. The following example shows the
runtime state of several containers:

The containers shown in this figure are:

DomainManager The default name of the domain managers container makes it


easy to recognize. It is highlighted in green, indicating that it is running and all its
hosted components are online.

myHost The default name of the additional broker in a typical SonicMQ install
takes the name of the host system. It is highlighted in red, indicating that it is not
running (and therefore its hosted components are offline.)

Service 1 Container through Service 5 Container The five management


containers used for services installed in this domain are all running and the container
that is expanded, Service4 Container, shows that its hosted component Service4 ESB
Container is online.

VerificationContainer Hosts the service to verify a containers setup is offline. See


Verifying an ESB Container Installation in the Progress Sonic ESB Product Family:
Installation and Upgrade Guide for more information about using this container.

24

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sonic Management Console


5.

If you have another domain running, connect to it. The following figure shows two
domain connections in a Sonic Management Console.

The following section explains how to work with the ESB Configured Objects section in
the Configure tab of the Sonic Management Console.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

25

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

ESB Configured Objects


The ESB Configured Objects section, located in the Configure tab of the Sonic
Management Console, enables you to configure ESB Containers, endpoints, services, and
ESB processes. The following procedure describes how to work with the ESB Configured
Objects section in the SMC.
Note The ESB Configured Objects section is available when:
1.

The Sonic installation where the Sonic Management Console (SMC) is launched
includes both the SonicMQ tools and the Sonic ESB tools.

2.

A domain where the Management Console is connected has been enabled by a Sonic
ESB Tools installation.

If the Sonic ESB Tools are not installed for this SMC, yet the domain is enabled for Sonic
ESB, the ESB Configured Objects section is not shown. You can see the /System files for
SonicESB and the /ESB Containers objectsusing a default iconas shown:

You should not attempt to manipulate these objects under these circumstances.
In the reverse casethe Sonic ESB tools are installed for this SMC, but the connected
domain is not Sonic ESB enabledthe ESB Configured Objects section is not shown.
See the Progress Sonic ESB Product Family: Installation and Upgrade Guide for
information about tools installations and the option to specify a domain to be enabled for
the tools.

26

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Configured Objects


To work with the ESB Configured Objects section in the SMC:
1.

With the Sonic Management Console connected to a domain that has been enabled
for Sonic ESB, the ESB Configured Objects section is available in the Configure tab:

This section can be expanded and contracted by double-clicking ESB Configured


Objects. In this example, the section is shown expanded.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

27

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools


2.

In the left panel, click on a container node in the ESB Containers folder, as shown:

The services in the selected ESB Container are listed in the right panel.
3.

28

Click on a name in the right panel to display its information and modifiable
parameters.
See Overview on page 50 for more information about ESB Containers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Configured Objects


4.

Click on an endpoint name in the Endpoints folder, as shown:

The endpoints for the selected endpoint name are displayed in the right panel. A tab
provides access to the connections for the selected endpoint.
5.

Click on an endpoint name in the right panel to display its information and modifiable
parameters.

6.

Choose the Connections tab to see the connections.

7.

Click on a connection in the right panel to display its information and modifiable
parameters.
See Configuring Progress SonicMQ Endpoints on page 95 for more information
about endpoints.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

29

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools


8.

In the left panel, click on a service in the Services folder, as shown:

The services of the selected Service type are listed in the right panel.
9.

30

Click on a service in the right panel to display its information and modifiable
parameters. Note that each service type shows its own unique set of initialization
parameters.
Some initialization parameters specify explicit values, and some specify variables. If
an initialization parameter specifies a variable, and the initialization parameter is
editable, you can modify the variable value directly. If you specify a variable, the
system replaces the variable with a parameter value at runtime.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Configured Objects

When a variable is used, the system has to obtain an actual parameter value from a
data source. To determine the data source, the system examines the variable itself. The
variable's syntax indicates where the system can find the parameter value. The syntax
for variables is show below (the dollar sign, braces, and colons are literals; the
brackets enclose optional elements):
${variable_source_type:[source_type_qualifier:]parameter_identifier}

where variable_source_type is one of the following string literals:

container The parameter value is defined in the deployment properties of the


ESB container into which the service type is deployed.

system The parameter value is defined in a JVM system property.

property The parameter value from a Java properties file.


and source_type_qualifier is the following string literal:

dynamic The parameter value is dynamically extracted from a specified


properties file. This qualifier is required if variable_source_type is property and
you do not want the property file read from a local cache.
and parameter_identifier is one of the following:

A valid SonicFS URL indicating a property in a Java properties file for


example:
${property:sonicfs:///workspace/myProject/src/myService.properties#myProp}

Name of an ESB container property or name of a JVM system property. If it is the


name of an ESB container property, variable_source_type must be container. If it
is the name of JVM system property, then variable_source_type must be system.
You can edit variables directly, or you can use the Global Parameter dialog box.
For more information, see the Progress Sonic ESB Product Family Developers Guide
in the Eclipse help.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

31

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools


10.

Click on Processes, as shown:

The processes are listed in the right panel. In the right panel, choosing a process
displays its information and modifiable parameters.
For more information, see the Progress Sonic ESB Product Family Developers Guide
in the Eclipse help.

32

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Admin Tool and Commands

ESB Admin Tool and Commands


While you can perform most configuration and administrative tasks with the Sonic
Management Console, you can also use the ESB Admin Tool to configure Progress Sonic
ESB containers and components, and to manage the lifecycle of Progress Sonic ESB
components deployed in management containers. You can also use the ESB Container to
manage the Directory Service (SonicFS). One of the most common uses of the ESB
Admin Tool is to import and export service types, services, endpoints, and connections.
See the Progress Sonic ESB Product Family: Deployment Guide for information on using
ESB Admin commands to move configurations from one domain to another.
To start the ESB Admin Tool:
1.

Select Start > Programs > Progress > Sonic 7.6 > Tools > ESB Admin Tool.
The ESB Admin Tool console window opens.

2.

In a default installation, enter the following to connect to the domain manager:


connect Domain1 tcp://localhost:2506 Administrator Administrator

See the following sections and the connect command for additional information.
After using the ESB Admin Tool, follow this procedure to stop the session.
To stop an ESB Admin Tool session:

In an ESB Admin Tool console window, type exit or bye and press Enter.

Each of the ESB Container commands is described in the following section.


Note ESB Admin Tool commands are not case sensitive. Many values are case sensistive; for

example, trying to connect to Domain1, yet entering domain1 will not succeed.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

33

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

Basic Commands
Most of the commands act on a connected Directory Service store so connect is typically
the first command entered in an ESB Admin session.
connect
connect domain URL [username password] [managementNode]

Connect to the domain manager at the specified URL. For example:


connect Domain1 tcp://myHost:2506 anAdmin aPwd

where:

is the Directory Service store where administration will occur.


URL is the IP address or DNS name resolvable to the broker and port of a management
broker of Domain in the form protocol://host:port. A URL list can be used when
delimited by commas and enclosed in quotes. For example:
Domain

connect Domain1 tcp://myHost:2506,tcp://myHostBackup:2506 anAdmin aPwd

username password are

the administrator credentials for authentication on the broker.


managementNode is the routing definition name on the non-management broker or
cluster that routes management communications to the management node. For more
information, see the Management Over Dynamic Routing in the Multiple Nodes
and Dynamic Routing chapter of the Progress SonicMQ Deployment Guide.
Note that the syntax of the connect command requires that, if you need to specify a
managementNode, username and password must be specified as well.

disconnect
disconnect

Disconnect from the domain manager.


exit
bye

exit

The exit commands stop the tool and close its window.
help
help

The help commands list the available ESB Admin commands and their syntax.

34

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Admin Tool and Commands

SonicFS Maintenance Commands


The following file and Directory Service actions are used in maintenance of the Sonic File
System, SonicFS.
add file
add file name filename [override]

Add a file as a resource to the domain with the specified name. If a resource already exists
with that name, the command fails unless you specify override on the command line.
For example, to import PO.xml to the specified location in SonicFS, creating f1 and f2 in
the process:
ESBAdmin> add file /f1/f2/PO.xml C:\PO.xml
Adding file into Directory Service...
name
= /f1/f2/PO.xml
file
= C:\PO.xml
override = false

For example, to import C:\PO.xml to /Resources in SonicFS:


ESBAdmin> add file PO.xml C:\PO.xml
Adding file into Directory Service...
name
= PO.xml
file
= C:\PO.xml
override = false

add directory
add directory sonicfs_directory source_directory

Recursively add the specified source directory (on disk) to the SonicFS in the Directory
Service store. The sonicfs_directory argument can specify a fully qualified path in
SonicFS. If sonicfs_directory is not fully qualified, it is assumed to be in the /Resources
directory in SonicFS.
For example, to add the local directory, myDir, to SonicFS:
add directory /Resources/myDir c:/myDir

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

35

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

delete file
delete file filename

Delete the file named filename from the domain. If a fully qualified path is not specified,
the file is assumed to be in the /Resources directory in SonicFS.
For example, to delete def.xml from the /Resources directory in SonicFS:
delete file def.xml

delete directory
delete directory sonicfs_directory

Delete the specified directory from domain


Also deletes all subdirectories and files in those directories.
export file
export file name filename

Export a file from the domain to the specified file and path. The export command is
supported for all file types and supports paths and explicitly specified directories. The
name argument can specify a fully qualified path in SonicFS. If name is not fully qualified,
the file is assumed to be in /Resources.
For example, to export def.xml from /Resources in SonicFS to c:\Testfiles, enter:
export file def.xml c:\Testfiles\def.xml

export directory
export directory sonicfs_directory target_directory

Recursively export the specified directory from the domain to the specified target
directory.

36

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Admin Tool and Commands

ESB Type Maintenance Commands


Several commands that perform actions in the connected domain are qualified by a type
value. The list and dump commands can optionally specify a type. The import, export,
and delete commands require a type parameter to refine the scope of their action.
The following types are valid for the ESB Admin Tool commands that use the type
variablelist, dump, export, import, and delete:
Type Value
accessor
connection
connectionType
endpoint
endpointType
file
license
params
process
service
serviceType
xq_container

list
list [type]

List the names of configurations in the domain. For example, to list the available types:
list

To list the service types in sonicfs:///Resources:


list serviceType

The list command can be constrained to specified directories. For example, to list the
contents of /f1/f2:
list file /f1/f2

If /f1/f2 are subfolders in the /Resources folder, specify the full location:
list file /Resources/f1/f2

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

37

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

dump
dump [type] [name] [filename]

Dump is an advanced command. You might be requested to use a specified dump syntax
by Sonic technical support.
To dump all available types, enter dump.
To dump a type, add the type value you want. For example, to dump the endpoints, enter
dump endpoint. The result is a file on the local file system named dump.txt that has all the
endpoints in XML format. The file is placed in the start directory of the tool,
sonic_install_dir/MQ7.6/bin.
dump endpoint ESBSampleQ9

Generates a file on the local file system named dump.txt that has only the endpoint
ESBSampleQ9 in XML format.
dump endpoint ESBsampleQ9 C:\dumpedQ9.txt

Generates a file on the local file system at C:\dumpedQ9.txt that has only the endpoint
ESBSampleQ9 in XML format.
A dump in XML format is useful for storing information, but you should use export rather
than dump in deployments.
export
export type name filename

Export a configuration from a specified type into the domain as the specified file.
The export command supports all configuration types.
import
import type filename [override]

Import a configuration from a specified file into the domain as the specified type. If a
configuration exists with the name defined in the body of the XML file, the command
fails. Specify override to force an overwrite of an existing configuration.
delete
delete type name

Delete a configuration from the domain of the specified type and name.

38

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

License Container Commands

License Container Commands


You can add or export a Sonic ESB license key (control number) in the connected domain.
Within a domain, there is a single ESB license for each version.
add license container
add license container license_key [version]

Add the Progress Sonic ESB license key to SonicFS. The specified license key overwrites
any Sonic ESB license key already in SonicFS. Use the version parameter to add multiple
licenses. Specify the version in the format, Major.Minor, for example, 7.6.
export license container
export license container [version]

Display the license container to the console. Use the version parameter to export an earlier
versions license. Specify the version in the format, Major.Minor, for example, 7.6.
ESBAdmin> export license container 7.6
Displaying license key (control number) for version 7.6 ...
Control Number = nnnnnnnnnnnnnnn

Management Container Commands


Information about containers and operational actions in the connected domain can be
performed by the ESB Container.
container list
container list

Lists the management containers in the domain, with their state, view name, host (when
online), and components.
container shutdown
container shutdown container_name

Shuts down the specified management container (not ESB Container). For example:
container shutdown containerName

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

39

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

container status
container status container_name

Reports the status of a management container. For example:


ESBAdmin> container status DomainManager
Container Name = DomainManager, State = Online,
Container Config Name = /Containers/DomainManager,
Host = NBSRUSSO3.bedford.progress.com
Component Name = ActivationDaemon1, State = Online
Component Name = Broker1, State = Online

container [suspend | resume | reload]


container [suspend|resume|reload] container_name component_name

Perform the specified operation on the management container and ESB Container
(a component of the management container).

Deployment Tool Commands


Deployment tool commands are in the following categories:

Analysis for deployment

Exporting for deployment

Tailoring archives for import

Importing or merging for deployment

Analysis for Deployment


The analysis commandsdiff, mqdepends, mqrevdepends, and impactcontrast archive
files, file system structures, and Directory Service stores for differences and
dependencies.
Note The analysis commands are one aspect of the set of deployment tools used in Sonic ESB

deployments. See the Progress Sonic ESB Product Family: Deployment Guide for
information about this set of commands and the import and export tools that facilitate
deployment.
These commands do not require that a connect command was executed as they either work
with file systems and archives outside the Directory Service or establish their connections
within the command.

40

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

License Container Commands

The general syntax of the analysis commands is:

Uses one or more storeType, each with storeParams as follows:

The first -storeType storeParams identifies the source artifact store, and
the next -storeType storeParams identifies the target artifact store.

storeType is { xar | fs | ds }.

storeParams are:

When storeType is xar, the archive location on a file system

When storeType is fs, the root of the hierarchy on a file system

When storeType is ds, the management connection to a domain in the form:


domain url [username password] [managementNode]

Every analysis command produces an output file. The out parameter specifies the
preferred location of the .xml file that reports on the analysis. The directory hierarchy
you specify must exist for the command to succeed.
If you do not specify an output file, a default file is created in the ESB Admin Tools
working directory as follows:
Analysis Tool

Default Output File

diff

Sonic_Diff.xml

mqdepends

Sonic_Dependency.xml

mqrevdepends

Sonic_ReverseDependency.xml

impact

Sonic_ImpactAnalysis.xml

Some analysis commands provide a v switch to enable enhanced verbosity.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

41

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

diff
diff -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]

The diff command assesses the difference between two artifact stores. Unlike a generic
differencing engine, the ESBAdmin diff only assesses specific filetypes in certain store
types. The stores can be Sonic archive filesXAR files(-xar store type), file systems
(-fs store type), or Directory Service stores (-ds store type).
Differences include:

Artifacts that are in both stores yet do not have identical content. You can choose to
identify only that the files are dissimilar or to expose the differences in detail.

Artifacts that are in the source store but not in the target store

Artifacts that are in the target store but not in the source store
As an example, a command comparing a XAR file with a Directory Service store is:
diff -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPassword

mqdepends
mqdepends -storeType storeParams -out outputFile.xml
[-include artifact1 [artifact2 ...] | -includeFile artifactListFile]

where the optional parameters include:

artifact1 artifact2 ...(a series of specific files in the store to analyze)

artifactListFile (a text file that provides a list of files in the store to analyze)
The mqdepends command assesses a source artifact store to evaluate and report on the
dependencies of ESB artifacts on SonicMQ configuration objects. You can use this
information to create or verify the existence of the specified dependencies in a target
Directory Service store. The stores can be a Sonic archive file, file system, or a Directory
Service store.
Sonic ESB dependencies on SonicMQ artifacts include:

Endpoints for their destination dependencies (topics, queues, or routing).

ESB connections for SonicMQ connection parameters (and, therefore, the broker
location and port where static destinations must be created.
As an example, to produce a dependency report on specified files:
mqdepends -fs C:/myinstalldir/ESB -include processA serviceA serviceB

42

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

License Container Commands

mqrevdepends
mqrevdepends -storeType storeParams [-out outFile.xml]
[-include artifact1 [artifact2 ...] | -includeFile artifactListFile]

where the optional parameters include:

artifact1 artifact2 ... is a series of specific files in the store to analyze

artifactListFile is text file that provides a list of files in the store to analyze
The mqrevdepends command assesses a source artifact store to evaluate and report on the
dependencies of ESB artifacts on SonicMQ configuration objects. You can use this
information to create or verify the existence of the specified dependencies in a target
Directory Service store.
Reverse dependency produces the same set of information as a dependency. However, the
information indicates a required SonicMQ configuration element, and then the ESB
artifacts that depend on it.
As an example, to produce a reverse dependency report on a list of specific files:
mqrevdepends -fs C:/fileDir/ESB -includeFile artifactList.txt

Impact
impact -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]

Assessing impact on a Directory Service store requires a connect command to establish a


connection to the domain prior to invoking impact.
An impact analysis report combines features of diff and mqdepends. Together, these
features define the impact on the target store that would result from merging the source
store into the target store.
Because this report assesses impact, the following information is also included:

If a binary file type is different, the impact analysis report indicates that the file in the
source store will overwrite the one in the target store.

If a file exists in the source store but not in the target store, the impact analysis report
indicates that a new file will be added to the target store. However, if a file exists in
the target store but not in the source store, it is not reported as it is not impacted and
will not be affected by any import actions.

If a dependency indicates that SonicMQ configuration objects must be created, the


impact analysis report describes the requirement. Conversely, if existing SonicMQ
configuration objects are no longer required, the impact analysis report notes that fact.
As an example, to report on the impact of an archive on a Directory Service store:
impact -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPwd

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

43

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

Exporting for Deployment


The deployment export commands create bootfiles and exported artifacts for deployment
to other domains. The Progress Sonic ESB Product Family: Deployment Guide provides
information on using these commands.
export fs
export fs targetFileSysPath [sourceFileSysPath | exportPropFile | all]

Export to a file system path as a file structure.


export archive
export archive targetArchiveFile [sourceArchiveFile | exportPropFile | all]

Export to a Sonic archive file.


export bootfile
export bootfile container_config_name [filename]

Create a boot file to use when starting an ESB Container. By default a boot file is created
in the current working directory with the name, bootname.xml Optionally, specify a file
name to have the boot file created elsewhere.

Tailoring Archives for Import


The tailoring commands create intermediate files that are tuned for a target domain so you
can map archives for import into the domain to the characteristics of the target domain.
The Progress Sonic ESB Product Family: Deployment Guide provides information on
using these commands.
createMap
createMap archive_file map_file [rules file]

Create a tailoring map file that is edited and then applied to a Sonic archive using the
applyMap command.
applyMap
applyMap input_archive_file map_file output_archive file [log file]

Create a tailored archive from a source archive and a tailoring map file.

44

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

License Container Commands

Importing or Merging for Deployment


The import and merge commands transfer the source data into the connected domain.
The Progress Sonic ESB Product Family: Deployment Guide provides information on
using these commands.
import fs
import fs sourceFileSysPath [importPropFile | override]

Import into a domain from a file system path as a file structure where:

sourceFileSysPath is the root of the file system hierarchy that contains the files to be
imported into the connected Directory Services store.

One of the following arguments is used:

importPropFile When an import properties file was created and saved, it can
be applied as a parameter of the command to apply the defined overwrite and
ignore settings.

override Set overwrite of matching files to true.


import archive
import archive sourceArchiveFile [importPropFile | override]

Import into a domain from a Sonic Archive file.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

45

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

merge (standard form)


merge -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]

where:

The first -storeType storeParams identifies the source artifact store, and
the next -storeType storeParams identifies the target artifact store.

storeType is { xar | fs | ds }.

storeParams are:

When storeType is xar, the archive location on a file system

When storeType is fs, the root of the hierarchy on a file system

When storeType is ds, the management connection to a domain in the form:


domain url [username password] [managementNode]

The out parameter lets you specify the preferred location of the .xml file that reports
on the analysis. If you do not specify an output file, a default file (Sonic_Merge.xml)
is created in the ESB Containers working directory
-v requests verbose reporting

For example, to merge an archive into a Directory Service store:


merge -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPwd -out c:\out.xml

merge (compound form)


A variation in the syntax of the merge command enables the merger of two source stores
into a target store. As a result, the target store is acted on but the two source stores are
unmodified. The source and target stores can be XAR files, file systems, or Directory
Service stores.
The syntax of the advanced merge command in the Sonic ESB Admin Tool is:
merge -sourceStore1Type sourceStore1Params
-sourceStore2Type sourceStore2Params
-targetStoreType targetStoreParams
[-out outFile.xml]
[-v]

where the variation from a standard merge is that sourceStore1 and sourceStore2 are two
distinct source types with their respective parameters that will be sequentially merged into
the target store.
For example, to merge a XAR and a file system into a target file system:
merge -xar source.xar -fs C:/sourceDir/ESB -fs C:/targetDir/ESB -out c:\out.xml

46

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Shutting Down Sonic Components and Sonic ESB Tools

Shutting Down Sonic Components and Sonic ESB Tools


To shut down the tools and components in a Progress Sonic ESB environment, perform
an orderly shutdown of Sonic components, and then stop the tools. The following
procedure assumes that you want to stop all the components in connected domains, and
then stop the tools in the local installation.
If you want to stop all the components that are running on the local system where the tools
were started, connect to that domain so that you can perform actions on its components.
To perform an orderly shut down of Sonic components:

In each domain, shut down any running containers:


1.

In the Sonic Management Console, select the Manage tab.

2.

Choose the containers folders, typically /Containers

3.

Right-click on each container name you want to stop, and select


Operations > Shutdown.

4.

Be sure to shut down the container named DomainManager last.

The specified configuration objects are stopped.


To shut down Sonic ESB tools:
1.

Shortly after you stop a domain manager where tools are connected, you are prompted
that there is problem trying to resume connection. That is to be expected. Close the
open windows within the Sonic Management Console to stop their connections.

2.

If the JMS Test Client is running, close it.

3.

If the ESB Container is running, enter bye to stop it.

4.

In the Sonic Management Console, select Action > Exit.

The Sonic ESB tools are stopped.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

47

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

48

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 2

ESB Containers

Progress Sonic ESB is a framework composed of classes and APIs for architecting,
developing, and configuring distributed services. This framework includes an ESB
Container, a centralized configuration service, and key routing and processing services.
This chapter explains how to work with Sonic ESB Containers and describes services and
messages in the Sonic ESB framework.
This chapter contains the following sections:

Overview

Creating ESB Containers

Managing the Services Associated with an ESB Container

Deploying an ESB Container in a Management Container

Changing the State of Management and ESB Containers

Monitoring Service Metrics and Notifications

Enabling Integration with Actional for Visualization

Logging and Tracing

Using Activation Daemons


Note The tasks in this chapter are oriented toward deployment specialists. Sonic ESB Product

Familys development environment, the Sonic Workbench, manages ESB Containers,


starting and stopping them for you, often automatically. When you add or remove
services and processes to your development environment, you do not have to perform
most of the tasks described in this chapter. In the Sonic Workbench, you can perform
many of these actions in the Containers view. See the Sonic ESB Product Family:
Developers Guide in Sonic Workbench online help.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

49

Chapter 2: ESB Containers

Overview
ESB Containers host services, endpoints, and ESB processes. Configuration information
is provided to an ESB Container from a centralized Directory Service. The Directory
Service notifies containers of configuration changes and updates each containers cache
of configuration information. An ESB Container also provides access to a common log
file for all the services it hosts. In addition to ESB processes, services, and endpoints, ESB
Container components include:

Management framework access Provides access to the centralized configuration


store and standard facilities for managing the containers assets.

Connectivity components Manage connections and communication with external


resources, including JMS. They include the endpoint manager for access to existing
endpoints (by name) or creation of new ones.

Services and ESB processes Handle the application-level components or services


and manage the interaction of service code with the environment, including the
application manager (which controls the lifecycle of ESB services,) the service
application (which sets up each instance of a service) and the dispatcher (which
passes each message to a service and sends processed messages to the next destination
or endpoint.)

Factory objects Create instances of objects that services require:

MessageFactory Creates new messages to be sent.

EnvelopeFactory Creates new envelopes to associate messages with addresses.

AddressFactory Creates addresses for envelopes allowing messages to be sent


to an ESB process, service, or endpoint.
An ESB Container manages the lifecycle of services and creates a pool of connections to
JMS endpoints (destinations). Each ESB Container within a Sonic domain must have a
unique name.

50

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Overview

When an ESB Container starts up, it follows this sequence:


1.

The management container reads its local boot file. This file contains the name of the
management container as well as the connection information (URL, username, and
password) used in enabling the management communications layer. The connection
information must be the same as that used by the Directory Service. This file can be
encrypted (see the Configuring Framework Components chapter in the Progress
SonicMQ Configuration and Management Guide).

2.

The container enables management communications and makes a request for its basic
configuration information.

3.

The Directory Service replies with the name of the ESB Container in the management
container (plus other components, such as an Activation Daemon).

4.

The configuration of the ESB Container is requested.

5.

The Directory Service replies with the list of services to be run within the ESB
Container.

6.

The ESB Container starts its internal components, including services and
connections. This often involves additional requests from the Directory Service for
additional configuration information.

7.

During startup, the ESB Container might make additional JMS connections required
by the services it supports. These connections are independent of the initial
management connection. Typically, the usernames and passwords for these
application connections are different from the username and password used for
management connections.

A running ESB Container continues to make management requests on its own and
responds to administrative requests from the management tools, such as the Sonic
Management Console. Some reasons for this additional communication include:

Additional configuration information is needed by a service. These requests are


directed to the Directory Service, (for example, process configurations.)

Management tools send life cycle management commands to the management


container, for example, to suspend operation, reload configuration information, or
initiate a shutdown operation.

Requests for status from other components or tools.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

51

Chapter 2: ESB Containers

The following events occur as the ESB Container manages message transfer:
1.

The ESB Container reads configuration information from the Directory Service.

2.

The ESB Container establishes JMS connections to Progress SonicMQ destinations


(topics or queues).

3.

The ESB Container pools JMS connections.

4.

Messages arriving on their Progress SonicMQ destinations are allocated to services


that implement the XQService interface by calling their service( ) method, using the
predefined Quality of Service (QoS)EXACTLY_ONCE, AT_LEAST_ONCE, or BEST_EFFORT.

5.

Messages are processed by the services.

6.

Output messages are generated by the services and placed in an OUTBOX.

7.

Messages in the OUTBOX are sent to SonicMQ destinations by the services, or to other
services in the container.

An ESB Container is deployed as a component in a management container. The


management container caches all the information that it looks up in its domain managers
Directory Service store. If the domain manager is not accessible and the management
container is not looking up any new configurations (including resources such as
stylesheets, new services, or endpoints) at that time, then the container can continue
running despite the domain manager failure. However, if a new configuration is necessary
that is not cached, it must wait for the Directory Service to be restarted.
In addition to providing configuration information, a management container also provides
access to a common log file for all of the components it hosts. (For information on
container caching and logging, see the Configuring Containers and Collections and
Managing Containers and Collections chapters in the Progress SonicMQ Configuration
and Management Guide.)
The following sections describe how to manage installed ESB Containers and create new
ESB Containers. Use the Sonic Management Console to add Progress Sonic ESB
components to a container.

52

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Creating ESB Containers

Creating ESB Containers


The following procedure describes how to create an ESB Container using the ESB
Configured Objects section of the Sonic Management Console.
To create a new ESB Container:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, click the ESB Containers folder.

2.

In the right panel, click New. The entry fields for the ESB container are as shown:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

53

Chapter 2: ESB Containers


3.

In the ESB Container Maintenance section, specify the following properties:


Property

Description

Name

The name of the ESB container.

Intra-container
Messaging

Select to allow the container to bypass the overhead of sending and


receiving messages to and from endpoints when the services in that ESB
process reside in the same container.
Also used for all OUTBOX processing where dynamic routing is indicated
(when the target destination is a remote destination such as NodeA::T1).

ESB (JMS)
Connection

Specify the ESB connection used to call web services deployed on the
ESB (in contrast to those available at an external HTTP address.)

HTTP Routing
Connection

Specify the HTTP routing connection to the SonicMQ broker that is used
for web services with HTTP addresses.

For more information, see the Progress Sonic ESB Product Family Developers Guide in the

Eclipse help.
4.

In the Actional Integration section, specify the following properties:


Property

Description

Enable Actional
Instrumentation

Select this option to enable Actional Server visualization on this ESB


container. By default, the option is not selected (unchecked). See the
chapter on Instrumenting Sonic ESB in the Actional Interceptor
Guide.

Enable Payload
Capture

When Actional instrumentation is enabled, declares whether the


instrumentation should include the message body.

The Actional Integration feature requires Progress Actional software products to


provide visibility, control, and enforcement of deployed assets. See their Web site at
www.progress.com/actional.
5.

Click Apply to complete the definition of the ESB Container you created.

You now need to add services to the ESB Container.

54

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Creating ESB Containers


To add services to an ESB Container:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, exapand the ESB Containers folder.

2.

Select the ESB Container to which you want to add services, and then click New in
the right panel of the Sonic Management Console. The Select Service or Process to
Add to Container dialog box opens.
To select or create an element to add to your ESB Container, see Adding Services or
ESB Process Entry Points to an ESB Container on page 59 for detailed information.

3.

Click OK to close the Select Service or Process to Add to Container dialog box.
You do not have to add ESB Processes to containers unless you want to make them
directly accessible over a JMS Endpoint. This entry endpoint will only be used by
external JMS (or WS-Protocol clients.) ESB services sending to a process always go
to the first step.

Note

4.

Click Apply in the lower right panel of the Sonic Management Console to apply the
changes to your ESB Container.
The service or ESB process you selected appears in the right panel. You can repeat
this step to add services and ESB processes to your ESB Container.
(You can click Reset to restore the previously applied values before you click Apply.)
If you click Undo, any changes made before the previous Apply are undone. The
information reverts to its previous state and Redo becomes available. (Undo does not
undo the last change unless Apply has been clicked.)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

55

Chapter 2: ESB Containers

ESB Container Intra-container Messaging


Intra-container messaging allows a container to bypass the overhead of sending and
receiving messages to and from services in a process when the next service in an ESB
Process resides in the same container. When you select intra-container messaging for an
ESB Container, a message in the Outbox of one service (that is addressed to another
service in the same ESB Container) is sent directly the other service, bypassing the
broker.
Messages sent to a Sonic ESB service where intra-container messaging is enabled bypass
the broker, so any listeners outside the container will not receive these messages. The
Quality of Service (QoS) for the entire message dispatch through a process or chain of
services is dictated by the QoS of the entry endpoint of the service that first receives the
message off the originating JMS destination.
For example, when a service whose entry endpoint has a QoS of EXACTLY_ONCE receives a
message, that message will have QoS of EXACTLY_ONCE throughout the process until it
reaches another JMS destination, regardless of the QoS of any other services it passes
through after the first service. In this example, if a fatal error (such as a container crash,
machine crash, or power failure) occurs, a message that is not committed at the time of
failure will be resent when the container becomes available. The uncommitted message
is resent in this case because it retains the QoS of EXACTLY_ONCE. See Quality of Service
on page 102 for more information about QoS.

56

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Creating ESB Containers

Viewing or Editing ESB Container Properties


Follow this procedure to view and edit the properties of installed ESB Containers.
To view or edit the properties of installed ESB Containers:
1.

Start the Sonic Management Console. (See Using Progress Sonic ESB
Configuration and Management Tools on page 19.)

2.

In the left panel, under the ESB Configured Objects node, select the ESB Containers
folder.
The right panel lists any installed ESB Containers:

In this example, the ESB Container VerificationContainer is selected so its properties


are displayed.You can edit the properties for the selected container (except its name),
as described in Creating ESB Containers on page 53.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

57

Chapter 2: ESB Containers

Managing the Services Associated with an ESB Container


Services ESB Containerare deployed in ESB Containers. The following procedure shows
how to view information about the services in an ESB Container.
To view the services associated with an ESB Container:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, expand the ESB Containers folder and select an ESB Container. The
right panel displays information for the selected ESB Container. For example, select
dev_ESBCore.

You can sort the list of services by Name, Type, Listeners, or Entry Endpoint.
2.

58

Select a service to display information for that service, for example, dev.CBR:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Managing the Services Associated with an ESB Container

Adding Services or ESB Process Entry Points to an ESB Container


Follow this procedure to add a service or ESB process entry point to an ESB Container.
To add a service or ESB process entry point to an ESB Container:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, expand the ESB Containers folder, and then select an ESB Container.

2.

In the right panel, click New.


The Select Service or Process to Add to Container dialog box opens. To constrain
the list to services or processes, set either the Show Services or the Show Processes
icons.

Show Services
Show Processes

You can select from available services and ESB processes, or create services and ESB
processes from this dialog box.
You can sort the list by Name, Type, and/or Category.

3.

a.

Select a service or ESB process and click OK to return to the Sonic Management
Console.

b.

Click Apply. Progress Sonic ESB adds your selection to the list in the top right
panel.

To add a new service, select New > Service in the Select Service or Process to Add
to Container dialog box, and select a service type from the list. The Configure
Service dialog box for that service opens.
a.

Enter, accept, or select values for the fields in the Configure Service dialog box.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

59

Chapter 2: ESB Containers

4.

b.

Click OK to close the Configure Service dialog box. Your new service now
appears in the list of services and ESB processes in the Select Service or Process
to Add to Container dialog box.

c.

Select your new service and click OK to close the Select Service or Process to
Add to Container dialog box. Your new service is now set in the Service/Process
Maintenance area.

To add an ESB process, select New > Process in the Select Service or Process to
Add to Container dialog box, and select an ESB process type from the list, then click
New.... The Configure Process dialog box opens.
a.

Enter, accept, or select values for the fields in the Configure Process dialog box.
Click OK to close the Configure Process dialog box. Your new ESB process now
appears in the list of services and ESB processes in the Select Service or Process
to Add to Container dialog box.

b.

Select the new ESB process and click OK to close the Select Service or Process
to Add to Container dialog box. Your new ESB process is now set in the
Service/Process Maintenance area.

Important When you add a service or process to an ESB Container, the container must be restarted

to implement the changes.

Deleting ESB ContainerServices from an ESB Container


Follow this procedure to delete a service from an ESB Container.
To delete a service from an ESB Container:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, expand the ESB Containers folder and select an ESB Container.

2.

Select the service and click Delete.

3.

Confirm your selection. Progress Sonic ESB removes the selection from the list.

Important When you delete a service or process from an ESB Container, the container must be

restarted to implement the changes.

60

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Deploying an ESB Container in a Management Container

Changing the Number of Listeners on Services in ESB Containers


You can edit a service to change the number of listeners. Each listener is a thread.
To edit the number of listeners on a service associated with an ESB Container:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, expand the ESB Containers folder and select an ESB Container.

2.

In the right panel, select a service whose listeners you want to edit.

3.

Change the number of listeners to the value you prefer.

4.

After you make a change, click Apply to commit the changes.

Important When you modify a service or process in an ESB Container, the container must be

restarted to implement the changes.

Deploying an ESB Container in a Management Container


An ESB Container is deployed as a component in a management container. A component
is a software object meant to interact with other components, and encapsulating certain
functionality. A component has clearly defined interfaces and conforms to a prescribed
behavior common to all similar components within an architecture.
The following table lists the appropriate sections in the Configuring Containers and
Collections chapter in the Progress SonicMQ Configuration and Management Guide
that describe how to deploy an ESB Container in a container and other information about
containers.
Topic

Section

Creating a management container

Configuring Containers

Adding an ESB Container as a component in a


management container

Configuring Container Components

Generating a management container boot file

Generating Container Boot Files

Using fault tolerant (backup) management containers

Generating Containers

(Also see the SonicMQ Deployment Guide chapter


Fault Tolerant Application Containers.)
Note that there is no configuration for a fault tolerant
ESB Container.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

61

Chapter 2: ESB Containers

Setting Test Mode for ESB Containers Used in Development


To use a new ESB Container, the Sonic Workbench requires that you set the ESB
Containers property TEST_CONTAINER_MODE to true.
To set an ESB Container to Test Mode:

62

1.

Create an ESB Container, and then create a management container.

2.

Add the ESB Container to the management container as a component.

3.

Click on the management container. On the right panel, right-click on the ESB
Container component, and then choose Properties.

4.

Choose the Deployment Parameters tab, and then click Add.

5.

In the New Deployment Parameter dialog box, enter the Name TEST_CONTAINER_MODE
and the Value true. Click OK.

6.

The deployment parameter appears as shown:

7.

Click OK to apply the setting.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Deploying an ESB Container in a Management Container

Adding JAR files to an ESB Container


When you have JAR files used by the ESB Container, you need to import the .jar files
into the domain, and then set the classpath for each ESB Container that references classes
in those archives. The following procedure explains how to import a .jar file and set the
classpath for an ESB Container.
To import a .jar file and set the classpath for an ESB Container:
1.

In the Sonic Management Consoles Configure tab, select the configuration path
where you want to locate the .jar file.

2.

Select Action > Import. The archive is imported into the domain. In the following
example, a folder named myJars was created in the Resources folder, and then, with
the new folder selected, the archive myJarOne.jar was imported from the file system.

3.

Expand the ESB Containers folder, right-click on the ESB Container for which you
want to add the classpath, and select Properties.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

63

Chapter 2: ESB Containers


4.

Click the Resources tab, and then click Add. Navigate to your imported .jar file.

The sonicfs:/// prefix is added when you browse to the file location, as shown:

5.

Click OK to close the Add Classpath dialog box, then click OK to close the
Edit Sonic ESB Containers Properties dialog box. The .jar file is now on the
container classpath.

6.

Reload the container. You do not have to restart it.

Note You usually import archives and their classpath reference during the import process of

the service type.

64

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Changing the State of Management and ESB Containers

Changing the State of Management and ESB Containers


Follow this procedure to view and change the state of management containers and ESB
Containers.
To view and change the state of management containers and ESB Containers:
1.

Select the Manage tab in Sonic Management Console and select the folder that
contains the management containers.

Container state can be Online, Offline, or Unavailable.


You can sort the list of management containers by Name, State, or Last Error.
For each management container, you can view its ESB containers; and for each ESB
container, you can view its ESB services and ESB processes.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

65

Chapter 2: ESB Containers


2.

You can select a management container, right click, and select Operations to:
Operation

Description

Launch

Launches the container (provided that management container is


on the activation list of a running Activation Daemon deployed
where the management container is deployed.)
Choosing to launch lets you choose the activation and then the
container to launch.

Restart

Restarts the container

Shutdown

Shuts down the container

Reset Metrics

Resets container-wide metrics

Invoke Diagnostics...

Opens the Sonic Diagnostics dialog box.

For more information on management container operations, see the Managing


Containers and Collections chapter in the Progress SonicMQ Configuration and
Management Guide.
Warning Do not include an external jndi.properties file in the classpath of an ESB Container (or

even the classpath of the JVM used to launch the container), as this will prevent starting
the management container hosting the ESB Container.

66

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Changing the State of Management and ESB Containers


3.

4.

You can select a management container, right click, and select Container Log to:
Operation

Description

View

Views the contents of the container log.

Clear

Clear the contents of the container log.

Save to File...

Saves the container log to a file.

Select the management container you want to view. In this example, the management
container, dev_ESBCore, contains an ESB container of the same name
(dev_ESBCore), whose state is Online:

An ESB Containers state is Online, Offline, or Unavailable.


You can sort the list of ESB Containers by Name, State, or Last Error. For each ESB
container, you can view its ESB services and ESB processes. The color of each ESB
service or process indicates its state (green indicates the service or process is online,
and red indicates the service or process is offline or in an error state.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

67

Chapter 2: ESB Containers


5.

To perform operations on an ESB Container, right click on it, then select Operations:
Operation

Description

Start

Starts the ESB Container

Stop

Stops the ESB Container

Reload

Unloads the ESB Container, reloads configuration information, and


restarts services in the ESB Container

Abort

Aborts the ESB container, its ESB services, and its ESB processes.

Clear Error

Clears the last error.

Reset Metrics

Resets container-wide metrics.

For more information on component operations (ESB Containers are components in


management containers), see the Managing Containers and Collections chapter in
the Progress SonicMQ Configuration and Management Guide and the Contaniers
view in the Sonic Workbench.
6.

To perform operations on an ESB service, right click on it, then select Operations:
Operation

Description

Start

Starts the ESB service.

Stop

Stops the ESB service.

Abort

Aborts the ESB service.

For more information on ESB container and ESB service lifecycle operations, see the
Progress Sonic ESB Product Family: Developers Guide in the Sonic Workbench
online help.

68

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Monitoring Service Metrics and Notifications

Monitoring Service Metrics and Notifications


All ESB services deployed in an ESB container support standard metrics and
notifications.

Standard Metrics
All ESB services deployed in an ESB container support the following metrics:

esb.service.messages.Received Records the number of message envelopes


receivedthat is, the number of times service has been invoked on the service
instance. This metric includes any messages received intracontainer, through
dynamically registered entry endpoints, and so on.

esb.service.messages.ReceivedIntraContainer Records the number of message


envelopes received intracontainer.

esb.service.messages.ReceivedPerSecond Records the rate per second at which


this service has been invoked over the collection interval.

esb.service.messages.ReceivedPerMinute Records the rate per minute at which


this service has been invoked over the collection interval.

esb.service.messages.ReceivedPerHour Records the rate per hour at which this


service has been invoked over the collection interval.

esb.service.messages.Rejected Records the number of message envelopes that


were rejected by the service instance.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

69

Chapter 2: ESB Containers

esb.service.messages.Faulted

Records the number of message envelopes that


produced one or more faults. This metric does not record the actual number of fault
messages produced, as in some cases a single invocation can result in many fault
messages.
esb.service.messages.AverageProcessingTime Records the average time (in ms) it
has taken to process a message. This measures the time for the service instance to
return from a call to service; it does not account for processing time before the ESB
framework passes the message to the service instance, or processing time after the
service instance has returned control to the ESB framework.
esb.service.messages.SentWithDispatch Records the number of messages sent
using XQDispatch.
esb.service.messages.SentWithCall Records the number of messages sent using
XQEndpoint.call.
esb.service.messages.SentToOutbox Records the number of messages sent to the
service outbox. A single message received may result in zero, one, or many messages
in the outbox.

To enable a service metric:

70

1.

Open the Sonic Management Console and select the Manage tab.

2.

Select a running ESB Container.

3.

Right-click on the ESB container and select Metrics.... The Monitoring dialog box
opens with its Metrics tab:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Monitoring Service Metrics and Notifications


4.

Select one metric or a group of metrics (by selecting the parent folder) and select
Enable. The Sonic Management Console enables the metrics you selected, for
example, the entire group of message metrics:

If you select an individual metric, more options become available. You can disable the
metric or watch the metric in a Metrics Watcher window in both a bar chart and line
graph. For information on watching and disabling metrics, as well as general
information on metrics, see the Monitoring chapter in the Progress SonicMQ
Configuration and Management Guide.

Standard Notifications
Notifications are associated with the delivery of event information. The ESB Container
registers service notifications with the management container. The Sonic Management
Console subscribes to notifications and can display notifications in a Watch window.
The following standard service notifications are supported:

Service started successfully

Service failed to start

Service stopped successfully

Service failed to stop

Service aborted

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

71

Chapter 2: ESB Containers


To monitor notifications:
1.

Open the Sonic Management Console and select the Manage tab.

2.

Select a running ESB Container, right-click on the container, and select


Notifications... . The Monitoring dialog box opens with its Notifications tab:

3.

You can select one or more notifications, and for each notification, select Watch and
select whether to watch:

By Component (ESB Container)

By Container (management container)

By Domain

The Sonic Management Console marks notifications that are being watched:

The Sonic Management Console opens a Notification Watcher.

72

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Enabling Integration with Actional for Visualization

For general information on notifications and on watching notifications and viewing


notification attributes, see the Monitoring chapter in the Progress SonicMQ
Configuration and Management Guide.
See also the Progress SonicMQ Administrative Programming Guide and the Progress
Sonic Event Monitor Users Guide documentation for information on other options for
tracking these notifcations.For information on watching and disabling metrics, as well as
general information on metrics, see the Monitoring chapter in the Progress SonicMQ
Configuration and Management Guide.

Enabling Integration with Actional for Visualization


An ESB Container can integrate with Actional, the enterprise-class management and
runtime governance solution that enables users to secure, govern and manage Web
services and SOA processes from end to end. Actional gathers message data and enforces
policy as messages flow through the Services Network, dynamically mapping each and
every transaction.
The Actional Agent is a separately licensed component in the Actional product family.
The Actional Agent software includes interceptors (included in an ESB installation) and
the standalone Analyzer which must be installed separately. The interceptor monitors
traffic flowing through the ESB, while the Analyzer collects information from the
interceptor and forwards statistical information to an instance of the Looking Glass Server
(also available separately).
The Actional Agent can analyze Web service and JMS traffic on the Enterprise Service
Bus. When you enable Actionals interceptor technology on existing ESB infrastructures,
the Analyzer lets you gather data from this interceptor and communicate with an instance
of Actional Server.
The Actional ESB Interceptor is included in an ESB installation; however, it is not
enabled by default. To use the Actional Agent to manage ESB services and processes,
connect the Sonic Management Console to a Sonic domain you want to instrument, and
then select the option to Enable Actional Instrumentation on each ESB Container you
want to enable, as shown:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

73

Chapter 2: ESB Containers

To activate an enabled interceptor requires that the Actional Agent is installed and
running, and that the Agent node is under management by an Actional Server.
If the Actional Agent is not running before the instrumented Sonic ESB Containers are
started, you must restart the enabled Sonic ESB Containers to activate the Actional
visualization feature.
Important If the Actional Agent is installed with a non-default \link directory (the directory where

the Actional Agent creates Uplink.cfg), you must specify the path to the link directory
as a Java system property on the Environment tab of each management containers
properties with the Variable name com.actional.lg.interceptor.config and, for the
Value, the complete path, such as usr1/aUser/Actional/ActionalAgent/LG.Interceptor.
Note When using Actional to view an ESB process that makes a SOAP web service call, the

display might not be correct if that web service is running on a machine which is under
Actional management. The process and the remote web service might appear to be
disconnected. To view these interactions properly, remove the web service from
management through the Actional Server administration interface. Web services that are
running on unmanaged Actional nodes are not affected by this and render correctly.
See www.progress.com/actional for more information. The Instrumenting Sonic ESB
chapter in the Actional Interceptor Guide in the Actional Agent documentation set
provides details and illustrations of this feature.

74

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Logging and Tracing

Logging and Tracing


You can turn debug tracing on and off for ESB Containers and specify logging categories
to send messages to the containers message log. The following procedures describe how
to specify logging and tracing and how to make the settings permanent.
For more information on logging and tracing, see the Managing Containers and
Collections chapter in the Progress SonicMQ Configuration and Management Guide.
To specify logging and tracing for an ESB Container:
1.

In the Sonic Management Console, select the Manage tab and select the management
container that hosts the ESB Container.

2.

Right-click on the ESB Container and select Properties.

3.

The identity and status of the ESB Container is displayed:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

75

Chapter 2: ESB Containers


4.

Select the Tracing tab and then select tracing bit masks. In this example, Verbose, Set
Attributes, and Enable Debug Messages are selected.:

These settings include:

Enable Debug Messages (16) Enables application code to generate log output

ESB Invocation Script Tracing (64) Logs generic script engine events

Message Dispatch Tracing (128) Traces in, out, and fault messages

JMS Endpoint Tracing (256) Traces events related to endpoint creation and

usage

ESB Container Tracing (512) Traces ESB Container-specific events, for

example, lifecycle events


5.

Click OK to apply the settings.

Setting tracing on the running container sets it only for the current execution of the
container. Restarting the container resets the tracing selections to their standard
configuration values.
The following procedure describes how to set standard configuration values so that the
tracing options are set whenever the ESB Container starts.
Important While tracing provides valuable information, the logs grow faster than usual when tracing

settings are always active. Try some tracing settings and observe the amount of data that
they add to the logs. Then, try to reserve verbose settings to debugging activities only.

76

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Logging and Tracing


To make logging and tracing for an ESB Container permanent:
1.

On the Configure tab in the Sonic Management Console, select the management
container that hosts the ESB Container on which you want to maintain logging and
tracing.

2.

In the right panel, right-click on the ESB Container,and then select Properties.

3.

In the Edit Container Component Properties dialog box, enter the sum of the integer
values for each tracing bit you want to set, as specified in the Edit Sonic ESB
Container Properties dialog box.
In this example, Verbose (1), Set Attributes (2), and Enable Debug Messages(16) are
intended so the sum of 1+2+16, 19 is entered as the Tracing Mask value as shown:

These tracing bits are set in the runtime whenever this container starts.
4.

Click OK to apply the setting. The changed value is immediately applied to the
runtime settings.

Note Tracing options are also available on the management container as temporary runtime

overrides and standard settings that are re-established when the management container
restarts.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

77

Chapter 2: ESB Containers

Using Activation Daemons


Using an Activation Daemon is a way to launch new containers as spawned processes of
the container hosting the Activation Daemon. This allows new containers to be launched
by remote administrative clients without the administrator having to log on to that host. A
typical use would be to have the container hosting the Activation Daemon launched as a
Windows service on Windows platforms or a startup process under UNIX.
An Activation Daemon monitors the health of its spawned containers and, depending on
configured rules, restarts those containers upon failure. Normally, one Activation Daemon
is deployed per host. Multiple Activation Daemons can be created per domain.
Containers can be launched by the Activation Daemon:

At Activation Daemon startup time

At a configured time

After a container failure (up to a configurable number of retries)

On demand from the Sonic Management Console or through the Activation


Daemons management API (see the Using the Runtime API for the Sonic
Management Environment chapter in the Progress SonicMQ Administrative
Programming Guide)
This section demonstrates how to create and configure an Activation Daemon to start an
ESB Container. As an example, the procedures describe how to create an Activation
Daemon to automatically start the Service5 container when the Activation Daemons
container starts. See the Configuring Framework Components chapter in the Progress
SonicMQ Configuration and Management Guide for detailed information on using
Activation Daemons. The steps required to create, configure, and test the Activation
Daemon are:

78

1.

Creating an Activation Daemon on page 79

2.

Adding an Activation Daemon to a Management Container on page 79

3.

Adding an ESB Container to an Activation Daemons Activation List on page 81

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Using Activation Daemons

Creating an Activation Daemon


Create an Activation Daemon from the Sonic Management Console, as shown in the
following procedure. As an example, this procedure creates AD_for_Services.
To create an Activation Daemon:
1.

Start the domain manager where you want to manage the configurations.

2.

Start the Sonic Management Console, and then connect to the domain manager.
See Overview on page 20 for instructions.

3.

In the Sonic Management Consoles Configure tab, right-click the folder where you
want to create the new configurations. For this example, choose Containers.

4.

Right-click on the folder, and then choose New > Configuration > Sonic Management
Environment > Activation Daemon. For this example, name it AD_for_Services.
The New Activation Daemon dialog box opens.

5.

Specify the name of the Activation Daemon in the Name field.

6.

Click OK.

Adding an Activation Daemon to a Management Container


The following procedure shows how to add an Activation Daemon to a management
container. Typically, an Activation Daemon hosts the Activation Daemon in a
management container of its own and to assign other management containers to the
Activation Daemons activation list (which will, in turn, start their hosted components.
(See Using Activation Daemons in the Progress SonicMQ Installation and Upgrade
Guide for an illustration.)
As an example, this procedure adds a new Activation Daemon named AD_Services to a
new management container. When the management container starts, it will start this
Activation Daemon, and the daemon will launch its hosted components.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

79

Chapter 2: ESB Containers


To add an activation daemon to a management container:
1.

In the Sonic Management Consoles Configure tab, right-click the folder where you
want to create the new configurations. For this example, choose Containers.

2.

Choose New > Configuration > Shortcut to Container. For this example, name the
container AD_for_Services_on_myHost. Adjust the connection URL and the
username and password for management communications in the domain.

3.

Right-click on the container you created, and select Add Component. In the New
Container Component dialog boxs General tab specify:
Property

Description

Name

The name of the component you want to add to the container.


For this example, enter AD_for_Services.

Component

Click ... to open the Choose Component dialog box. For this example,
choose /Containers/AD_for_Services.

Auto Start

Specifies whether to automatically start the component when the hosting


container starts. For this example, check Auto Start.

Tracing Mask

Enter the tracing mask integer for this component.

For this example, the New Container Component dialog box should look like this:

4.

80

Click OK to add the component to the container.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Using Activation Daemons

Adding an ESB Container to an Activation Daemons Activation List


The following procedure describes how to add a management container that hosts an ESB
Container an Activation Daemons activation list. As an example, this procedure adds the
Service5 management container which hosts an ESB Container of the same name.
To add an ESB Container to an Activation Daemons activation list:
1.

In the Sonic Management Consoles Configure tab, navigate to the Activation


Daemon you created, then right-click on it.

2.

Choose Add Container to Activation List.

3.

Under the General tab, specify the following properties:


Property

Description

Container

Name of the container to associate with the Activation Daemon.


For this example, select ... then select Containers\Service5 Container and
click OK.

Number of
Retries

Number of times the ESB ContainerActivation Daemon should attempt to


restart the spawned container. For this example, use the value 4 instead of
the default value, 0.

Retry Interval

Number of seconds between attempts by the Activation Daemon to restart


the spawned container. For this example, use the value 15 instead of the
default value, 0.

For this example, your Add Container to Activation List dialog box looks like this:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

81

Chapter 2: ESB Containers


4.

Click OK. The Sonic Management Console associates the Activation Daemon with
the container you selected.
In this example, Service5 Container is added to the list of management containers for
AD_for_Services and will try to start four times at fifteen second intervals.

Note Setting JVM System Properties on a Management Container

You can maintainthe JVM system properties for a management container that is on an
Activation Daemons activation list by using the Sonic Management Console to open the
management containers Properties, and then choosing the Environment tab.
For example to specify the JNDI Initial Naming Context, specify the JVM system
property java.naming.factory.initial and set it to the
valuecom.sonicsw.xqimpl.jndi.spi.XQTNSContextFactory
Additional classpath settings are also set in the management container configuration.
For more information on management containers and their environment settings, see the
Configuring Containers and Collections chapter in the Progress SonicMQ
Configuration and Management Guide.

82

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 3

ESB Endpoints and Connections

This chapter first references to endpoints and ESB addresses, and then shows how they
are configured. Then connections are presented and shows how they are configured.
The chapter contains the following sections:

Overview

ESB Addresses and References to Endpoints

Evaluating Endpoint Requirements on JMS Destinations

Configuring Progress SonicMQ Endpoints

Fault Tolerant Connections and Reconnection

Every endpoint has an associated connection. The following procedure describes


how to view existing connections and configure a new connection.
Note In the development environment, the Sonic Workbench handles the creation of endpoints

and connections. For more information, see the Progress Sonic ESB Product Family
Developers Guide in the Eclipse help.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

83

Chapter 3: ESB Endpoints and Connections

Overview
ESB endpoints and connections enable communication among services. Endpoints are
destinations where ESB services send and receive messages. The definition of an endpoint
includes its connection, the URL address where the destination resides. An application
accesses a service by sending a request to the services entry endpoint.
Progress Sonic ESB endpoints include Java Messaging Service (JMS) destinations
queues and topicsthat are accessed through connections to SonicMQ messaging
brokers. Endpoints provide queuing and persistence between services. This persistence
allows an ESB process to be fault-tolerant and provides an overall Quality of Service
(QoS) that can guarantee processing in case of provider failure.
Endpoints are defined by three sets of properties:

Name A globally unique name for accessing the endpoint

Connection The logical connection that instantiates the endpoint

Parameters The specific parameters within the logical connection that distinguish
the endpoint (for example, the name of a Progress SonicMQ queue or topic)
The following view of an endpoint in the ESB Configured Objectssection of the Sonic
Management Console shows some of the properties:

84

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Addresses and References to Endpoints

Note Information for service developers Progress Sonic ESB uses endpoints when it

creates listeners for a service Inbox, or when it delivers messages from the Outbox.
However, as a service developer, you can also send messages directly to an endpoint from
inside a service:

To send messages as the output of the service, you simply place the message in the
services Outbox with the appropriate address.

To send messages synchronously (to wait for a reply on a temporary JMSReplyTo


destination), use the call( ) method on the endpoint.

To send messages asynchronously, use the XQDispatch.

ESB Addresses and References to Endpoints


When ESB services and ESB processes are configured, they are associated with an
endpoint that is used to receive messages (the entry endpoint). When messages are
delivered to a service (by the dispatcher), the message is placed in an envelope with an
address. An address is a generic term for ESB processes, services, or endpoints that can
serve as destinations for a service or process exit, fault, or regular message endpoint.
There is also a special REPLY_TO address for services configured as Request/Reply. If the
message sender is a service, the address is interpreted as an endpoint. Messages can be
sent directly to a ESB process or service (as well as to the endpoint itself).
ESB addresses include:

Endpoints A specific destination on a defined connection.

ESB processes Specifies binding to defined endpoints in their definition. That


endpoint is used in their first step (bypassing the entry endpoint)

Services Specifies binding to a defined entry endpoint of the service, or the service
itself when intra-container messaging is in use.
When you define a service or ESB process or adapt a service or ESB process to a target
domain, you specify four categories of ESB addresses: entry, exit, fault, and rejected
message. The following sections discuss each of these categories.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

85

Chapter 3: ESB Endpoints and Connections

Entry Endpoint
An entry endpoint always uses an endpoint address, a destination associated with an
underlying JMS topic or queue used as the entry into an ESB process or service. You can
use intra-container messaging to bypass the entry endpoint if the caller is in the same
container (see ESB Container Intra-container Messaging on page 56). Services that
must be accessed from remote JMS or HTTP clients or from itineraries that start in other
containers should have a JMS-capable entry endpoint.

Exit Endpoint
An exit endpoint can be any type of ESB address (or list of addresses.) It is the configured
last destination of an ESB process or service. The exit endpoint is typically configured as
REPLY_TO, a specially named endpoint that uses as the reply to destination name set on the
message that started the service operation or ESB process. The exit endpoint setting can
be overridden by an ESB process.

Fault Endpoint
A fault endpoint can be any type of ESB address. It is an endpoint to which application
messages with recoverable errors are sent. Messages are sent to the fault endpoint if
requested by the service.
Each service can have an optional fault endpoint for those messages it cannot handle. The
service decides which messages are sent to the fault endpoint as part of normal
processing. The fault endpoint can contain any valid message
The fault endpoint handles recoverable processing errors (for example, an out-of-stock
notice), and interruptions in the normal process that must be handled at the application
level.
The fault endpoint inherits the Quality of Service (QoS) settings of the service application
or ESB process.
The fault endpoint is often set as an address to another service or ESB process. It might
also be an endpoint (Progress SonicMQ destination) or a REPLY_TO destination.

86

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

ESB Addresses and References to Endpoints

Rejected Message Endpoint


The rejected message endpoint (RME) can be any valid XQAddress object including, an
endpoint, a service, and an ESB process. It handles messages that are an invalid type for
the process, messages that throw exceptions in the service() method of the service, and
messages that failed to send to their Fault or Outbox addresses. Messages that cannot be
processed are sent to the RME in the event of processing failures. This provides a similar
function to the SonicMQ Dead Message Queue (DMQ).
Every service can have an RME. Messages that cannot be processed are always sent to the
RME in the event of processing failures. The messages are sent to the RME by the
services framework, not directly by the services.
The RME handles:

Messages that throw exceptions in the service( ) method of the service

Messages that were in the services Fault box or Outbox, but which could not be
delivered (for example, the queue underlying the ESB endpoint does not exist.)
When a message is sent to a rejected message endpoint, it is sent as a multipart message.
The first part provides information about the rejected message, and the balance of the
messages is the original message. If the original rejected message was itself a multipart
message, the first part is the information section and the other parts follow it in the same
sequence as the original message parts.
The first part is a text/xml message with three sections:

rejectedCode A String identifier pointing to the reason for rejection (a list of


rejected codes is available in com.sonicsw.xq.ErrorCodes)

rejectedLocation The location of the failure; it can have these optional attributes:

locationName The name of the computer where the rejection occurred

containerName The name of the ESB Container that rejected the message

serviceName The name of the service that rejected the message

processName The name of the ESB process that was performing the action

stepName The name of the process step at which the message was rejected

rejectedString Details of the failure, including a stack trace of the failure or


exceptions causing the rejected message

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

87

Chapter 3: ESB Endpoints and Connections

Rejected Message Behavior Under Failure Conditions


This section describes the behavior of the process framework under various failure
conditions. Where appropriate, the com.sonicsw.xq.ErrorCode value is provided (the
value of the <rejectedCode>XXXX</rejectedCode> element of the rejectedMessageInfo
message).
A service should handle all generated exceptions itself. Normal service exit occurs
through the Outbox. All exception cases are handled by the Fault box.
Abnormal behavior is handled by the dispatcher using the RME. If the service( ) method
throws any exception or error (anything throwable, either java.lang.RuntimeException or
an XQServiceException), the original message is sent to the RME.
The rejectedMessageInfo\rejectedString is the stack trace of linked exceptions:
rejectedCode = XQ_SERVICE_EXCEPTION

Any processing error that occurs in the dispatcher before the message is delivered to the
service( ) method invokes the same RejectedMessageEndpoint behavior. The
rejectedMessageInfo is the stack trace of linked exceptions:
rejectedCode = MESSAGE_RECEIPT_FAILURE

When a QoS discrepancy occurs in the dispatcher between the QoS of the entry endpoint
and the QoS of the ESB process using it, the rejectedMessageInfo contains the intended
QoS:
rejectedCode = PROCESS_QOS_UNSUPPORTED_AT_ENDPOINT

An error outside the service(


sent to the RME.

method, delivering Inbox or Outbox messages, is also

The following scenarios result in rejected message processing:

If the address on an XQMessage in the Outbox or Fault box is invalid or empty:


rejectedCode = SEND_NULL_ADDRESS

If there is an error sending a message returned from the XQEndpoint.send(

) method:

rejectedCode = XQ_ENDPOINT_EXCEPTION

If some other error occurs in the dispatcher processing the message:


rejectedCode = MESSAGE_SEND_FAILURE

Time to live for an ESB process is checked when the message arrives at the service. If the
current time by the local system clock (measured in GMT) is greater than the ESB process
entry timestamp plus timeToLive, the RME is used:
rejectedCode = TIME_TO_LIVE_EXPIRED

Messages sent to the RME have the same QoS as the service from which they are rejected.

88

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Evaluating Endpoint Requirements on JMS Destinations

Evaluating Endpoint Requirements on JMS Destinations


When configuring JMS destinations for your applications, there are several factors to
consider as you prepare to configure the domain. The abstraction of ESB services and
processes from the specifics of the domain architecture make promotion of artifacts
through a series of stages or across various domains a fundamental task reserved for the
deployment manager rather than the developer.
Factors such estimated traffic volumes, available computing resources, the service level
requirements, the topology of the resourcesthese all contribute to the overall design of
the systems that broker the endpoints.

Will you run multiple instances of a service for scalability and reliability?

What quality of service (QoS) is required?

For EXACTLY_ONCE or AT_LEAST_ONCE QoS, messages can be sent PERSISTENT, and


topic subscribers should be durable.
See Using Concurrent Durable Subscriptions to Topics on page 91.

Are the destinations queues or topics?

If so, use queues, or topics with shared subscriptions. Normal topic subscriptions
broadcast a copy of all messages to each service instance.
See Using Shared Subscriptions to Topics on page 91.

If other applications are already sending to a destination, you cannot change that
destination.
If other applications are listening on the same destinations, you must use topics.
See When to Use Topics, When to Use Queues on page 90.

Does your deployment architecture have multiple brokers, clusters, or nodes?

When using queues, decide whether they should be global and/or clustered.
When using topics, decide whether they should be shared.
See Multiple Brokers, Clusters, and Nodes on page 93.

The recommended best practice for configuring JMS destinations is to use concurrent
durable subscriptions, which provide durability, scalability, and the ability to monitor
your applications.
Note In the Sonic development environment, endpoints are, by default, configured as

nonpersistent topics in the underlying SonicMQ domain. That helps ensure that a run or
test of a project does not interfere with subsequent runs after some services have failed
or became unavailable.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

89

Chapter 3: ESB Endpoints and Connections

Table 1 maps the destination configurations to destination requirements.


Table 1. Mapping Destination Requirements

QoS

Destination
Type
Multiple Services

Single Service Instances

AT_LEAST_ONCE

Topic

Concurrent durable subscription =


true
Shared subscriptions = true
Number of listeners = any number
Durable subscription name must be
non-null

or

EXACTLY_ONCE

BEST_EFFORT

Concurrent durable subscription =


false
Shared subscriptions = false
Number of listeners = 1
Durable subscription name must be
non-null

Queue

No additional configuration required

No additional configuration required

Topic

Concurrent durable subscription =


true
Shared subscriptions = true
Number of listeners = any number
Durable subscription name must be
null

Concurrent durable subscription =


false
Shared subscriptions = false
Number of listeners = 1
Durable subscription name must be
null

No additional configuration required

Queue

No additional configuration required

When to Use Topics, When to Use Queues


When deciding whether to use queues or topics in your applications, consider that the
underlying Progress SonicMQ layer provides some queue-like behavior for topics. The
shared subscription feature enables you to have persistent, load balanced topic subscribers
in your applications, while still allowing other subscribers on the topics.
If you use topics, other services can receive and process messages without interfering with
message flow through a process. Using this implementation, you can monitor business
activity with a monitoring service subscribed to one topic, while message flow continues
uninterrupted through a service subscribed to a different topic. This implementation is
also useful in debugging and testing your applications and processes.
See the Progress SonicMQ Application Programming Guide for a detailed discussion of
the features and benefits of using queues or topics in your applications. If you use topics,
there are other considerations in defining the endpoints that relate to the number of service
instances and the QoS. The following sections describe implementing concurrent durable
subscriptions and shared subscriptions on topics in Sonic ESB.
90

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Evaluating Endpoint Requirements on JMS Destinations

Using Shared Subscriptions to Topics


With topic subscriptions there can be cases where one application acting as a topic
subscriber cannot process messages as fast as messages are being published. This leads to
a bottleneck, where the subscribing application falls farther and farther behind.
You can establish groups of topic subscribers that share subscriptions to allocate the
message load among them. Within these groups, each message is delivered to, and
consumed by, only one member of the group. These group members can be located on
dispersed computers over diverse JMS connections. The implementation is compatible
with clusters of brokers so that the members of a consumer group can connect to different
brokers in a SonicMQ cluster. Regular subscribers, durable subscribers, and participants
in a shared subscription can be active concurrently on a broker.
Sonic ESB prepends the service name to the topic name when defining subscribers within
a group: [[ServiceName]]topicName. When you select a destination for a shared
subscription, Sonic ESB automatically prepends the service name to the topic you select
(if shared subscriptions are enabled for the service, which is the default condition).
For detailed information on implementing shared subscriptions, see the Publish and
Subscribe Messaging chapter in the Progress SonicMQ Application Programming
Guide.

Using Concurrent Durable Subscriptions to Topics


You can configure the entry endpoint of a service to define a durable subscription to a
topic. In Sonic ESB, multiple service instances can concurrently process messages sent to
a durable subscription.
Durable subscriptions are created using a unique prefix appended to the subscription
name configured on the JMS endpoint. The unique prefix consists of the management
container name, the name of the ESB service configuration (the service name), and the ID
of the message listener.
The Concurrent Durable Subscription setting on an endpoint is a boolean value:

When set to False, the number of listeners to is limited to one. Also, only one instance
of the service can be running anywhere in your ESB. This setting is preferred if you
care about guaranteeing order in processing. The effect is similar to setting Exclusive
on a queue.

When set to True, the default value, multiple containers are allowed to run the service,
and each of those containers can have multiple listeners. This setting is appropriate
when you want to load-balance and scale processing, and are not concerned about
order in processing.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

91

Chapter 3: ESB Endpoints and Connections

For detailed information on implementing durable subscriptions, see the Publish and
Subscribe Messaging chapter in the Progress SonicMQ Application Programming
Guide.
The following example illustrates Sonic ESBs naming convention for this feature:

A service named Service1 is deployed in MFContainer1 and MFContainer2.


Service1 has:

Two listeners in MFContainer1

One listener in MFContainer2

The subscription name is myDurableSub

The topic that is subscribed to myDurableSub is T1

These services share a subscription to the topic name [[Service1]]T1 (concurrent


durable subscriptions in Sonic ESB have shared subscriptions enabled by default)

The dynamically generated subscription names are:

MFContainer1:Service1:1:myDurableSub

MFContainer1:Service1:2:myDurableSub

MFContainer2:Service1:1:myDurableSub

Three durable subscriptions are created. Distribution to the durable subscriptions is based
on factors including the number of active clients and flow control status.
Each listener on a single service accesses the same, shared durable subscription, thus
improving the throughput of a deployed service instance by enabling concurrent message
processing. When a listener is eliminated, its durable subscription is not automatically
eliminated, which causes that durable subscription to remain inactive until the subscriber
returns .
Note

In conjunction with the shared subscription functionality, messages for a shared durable
subscription that might be stranded in these now-defunct subscriptions are re-allocated
to whichever shared subscribers are connected, whether durable or nondurable.
There is an advantage to using only durable subscribers in a shared subscription as a
failure of a regular subscriber without acknowledgement of a delivered message has no
mechanism for restarting and re-allocating the indoubt message.

92

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Evaluating Endpoint Requirements on JMS Destinations

Multiple Brokers, Clusters, and Nodes


The ability to access services over the underlying SonicMQ messaging layer is an
important consideration when a Progress Sonic ESB service calls out to other services and
expects a reply, or when a Progress Sonic ESB process connects many ESB services.
Sonics Dynamic Routing Architecture (DRA) is a robust, secure way to send messages
through a broker or cluster of brokers to a destination on another broker or cluster. (In
routing, each broker or cluster is a routing node. For more information on DRA, clusters,
and routing nodes, see the Multiple Nodes and Dynamic Routing and Clustered
Brokers chapters in the Progress SonicMQ Deployment Guide.)
In multi-node domains, Progress Sonic ESB uses DRA to make fewer direct connections
to remote nodes by using the ESB (JMS) connection and DRA routes to send to remote
nodes. (Every ESB Container has an ESB (JMS) connection. See Creating ESB
Containers on page 53 for information on specifying the ESB Container connection.)
When a message is sent to a node-qualified destination, the ESB (JMS) connection is used
to send the message to the broker associated with the ESB Container on the bus. You
configure an endpoint using a node-qualified queue or topic name to reference a queue or
topic on a remote node to which the client (ESB service) is not connected. For example,
you can configure the ESB (JMS) connection to NodeA (a routing node) and an endpoint
based on queue, NodeB::Q2. Messages travel over the DRA connection of NodeA to NodeB.
Progress recommends using this node-qualified syntax as a best practice, as it avoids
making new connections from an ESB Container to all the remote nodes. Progress
recommends using the node-qualified syntax even if you are not running over DRA
doing so eases the transition if you decide to implement DRA in the future.
The bus connection broker must have DRA routes defined for each of the remote nodes
that can be sent to. If not, sent messages go to the brokers dead message queue (DMQ).
Important If the DRA connection fails, the message goes to the DMQ rather than to the rejected

message endpoint (RME), provided the message is sent PERSISTENT and


JMS_SonicMQ_preserveUndelivered and JMS_SonicMQ_notifyUndelivered are set to true
(the Progress Sonic ESB QoS is AT_LEAST_ONCE or EXACTLY_ONCE on the process.) For
more information, see the Progress Sonic ESB Product Family Developers Guide in the
Eclipse help.
The only time the bus connection is not used is when the node is sonic.http, an HTTP
outbound routing node. In this case, the ESB Containers HTTP connection is used, as in
outbound web service invocations. (For more information, see the Progress Sonic ESB
Product Family Developers Guide in the Eclipse help.)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

93

Chapter 3: ESB Endpoints and Connections

Table 2 lists JMS destinations for endpoints when using queues or topics in the same
management domain. The table shows different configurations for brokers, clusters, and
nodes used by entry endpoints of called or invoked services.
Table 2. Destination Definition Conventions Within a Domain

Deployment

Queue Definition

Topic Definition

One broker

Use non-clustered queues

Use normal or shared topics

One cluster, multiple


brokers

Use clustered queues

Use normal or shared topics

Multiple nodes with


some nodes as
clusters, some as
brokers

Use global, clustered queues

Use either:

Use node-qualified entry endpoint


names, for example, Node::aQueue

Node-qualified entry endpoint names,


for example, Node::aTopic (shared
subscriptions are not allowed)

GSA and no overlapping topic names

When choosing JMS destinations for queues, consider the following:

For clustered brokers, you should use clustered queues

For multiple nodes, you should use global queues and entry endpoints that are
qualified by the node name
When choosing JMS destinations for topics, consider the following:

All topics are clustered and global

For multiple nodes, either use node-qualified names for the entry endpoint or use
global subscription architecture (GSA) and global subscription nodes. (For
information on GSA, see the Multiple Nodes and Dynamic Routing chapter in the
Progress SonicMQ Deployment Guide.

94

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Configuring Progress SonicMQ Endpoints

Configuring Progress SonicMQ Endpoints


The following procedure describes how to view existing Progress SonicMQ endpoints
and configure a Progress SonicMQ endpoint.
To view and configure Progress SonicMQ endpoints:
1.

In the ESB Configured Objects section of the Sonic Management Console, expand
the Endpoints folder, then click Progress SonicMQ Endpoint. The right panel lists
the available endpoints on the Endpoints tab.

2.

Select an endpoint from the list.


The ESB Configured Objects section of the Sonic Management Console displays the
properties of the selected endpoint, as shown:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

95

Chapter 3: ESB Endpoints and Connections


3.

Click New.
The right panel clears the endpoint property fields in the Endpoint Maintenance area.
Required properties in the Endpoint Maintenance and Init Parameters areas are
marked with an asterisk (*).

4.

Enter, accept, or select values for the following fields:

Property

Description

Endpoint Name

A unique name.

Connection

You must define at least one connection for each endpoint type. (The Connections tab
lists the currently defined connections. You can select one of the connections that ships
with Progress Sonic ESB, jms_defaultConnection or http_defaultConnection)

Quality of Service

Select one:

Best Effort The default. Messages are sent NON_PERSISTENT. There is no guarantee
that a message will not be lost. However, messages can be duplicated.

At Least Once Messages are sent PERSISTENT. Messages cannot be lost. However,

some services might have some messages redelivered in the event of a system failure;
others might not.

WSDL URL

Exactly Once The most reliable processing. Messages are sent PERSISTENT.
Messages are not lost, and services do not receive duplicate messages. EXACTLY_ONCE
is supported for endpoints that map to JMS destinations in either JMS domain as
supported by JMS1.1 (topic or queue) on the same JMS connection.

Optional (to associate an endpoint with a WSDL document that describes its interaction
model).
Enter the WSDL URL or click ... to open the Choose WSDL File Resource dialog box and
choose a WSDL file.

JMS Destination
Type

96

Select Queue or Topic.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Configuring Progress SonicMQ Endpoints

Property

Description

Destination Name

The name of a Progress SonicMQ topic or queue. You can either enter the name of an
existing destination in this field, or click New Queue... to create a new queue within a
specified broker or cluster. (Topics cannot be created in this way.)
When you click New Queue... the Create JMS Queue dialog box opens. Enter a
meaningful, unique Queue Name, and select a broker or cluster from the Create In list, then
click OK to create the queue in the named broker or cluster.
For information on configuring queues, see the Configuring Queues chapter in the
Progress SonicMQ Configuration and Management Guide.
See Using Shared Subscriptions to Topics on page 91 for information about destination
names when using shared subscriptions on topics.

Message Selector

Allows a consumer on the endpoint to filter and categorize messages in the message
header and properties with expression strings created with a subset of SQL-92 semantics.
This property is a java.lang.String that is evaluated left to right within precedence level.
(This property is not validated here.)
See the Message Producers and Consumers chapter in the Progress SonicMQ
Application Programming Guide for detailed information about message selectors and
syntax.

Concurrent
Durable
Subscription

Specifies whether the endpoint has a concurrent durable subscription to its destination
topic. This property ensures a unique subscription name so the topic can have multiple
listeners (this property does not dictate whether the subscription is durable). This property
is only relevant for topic-based endpoints. Multiple listeners in multiple service instances
can subscribe to the same durable subscription. This setting is optional, either True or
False; the default is True.

Durable
Subscription
Name

Name of the Progress SonicMQ durable subscription.


See Using Concurrent Durable Subscriptions to Topics on page 91 for information
about durable subscription names.

Priority

Optional. The priority at which Progress SonicMQ sends messages from this endpoint.
Enter a numeric value from 1 to 9 or Inherited; the default is Inherited. When this value is
set to Inherited, the priority of messages sent from this endpoint will be set to the value
with which the message was received, and new messages that are created and sent from
this endpoint will have a default priority of 4. When this parameter is set to a value from
1 to 9, all messages sent to this endpoint will have a priority equal to that value.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

97

Chapter 3: ESB Endpoints and Connections

Property

Description

Time to Live

The lifetime of messages within Progress SonicMQ sent from this endpoint. This optional
numeric value in milliseconds can be any positive integer:

Setting the value to 0 retains the message indefinitely.

Setting the value to an integer greater than 0 causes expired messages to be sent to the
DMQ if the QoS of the entry endpoint is AT_LEAST_ONCE or EXACTLY_ONCE. (For more
information on QoS, see Quality of Service on page 102.)

Setting the value to an integer greater than 0 causes expired messages to be lost if the
QoS of the entry endpoint is BEST_EFFORT.

Message Prefetch
Count

The number of messages the endpoint will consume in a single request from a Progress
SonicMQ queue when the endpoint is used as an entry endpoint. This property is only
relevant to queue-based endpoints. It is an optional numeric value; the default is 1. It can
override the value specified in Progress SonicMQ.

Message Prefetch
Threshold

An optional numeric value to specify that when the number of messages waiting to be
processed by the endpoint falls to, or below, this threshold, a new batch of messages will
be fetched. This number cannot exceed the Message Prefetch Count. This property is only
relevant for queue-based endpoints.

Shared
Subscriptions

Allows automatic load balancing (the default is True, enabling shared subscriptions).

Flow To Disk

Specifies whether messages sent to this endpoint flow to disk. This feature allows
messages to continue to flow when a subscriber to this endpoint is slower than the
publisher and the buffer of the subscriber is full. Specify one of the following settings:

For more information on shared subscriptions, see Using Shared Subscriptions to Topics
on page 91 and the Publish and Subscribe Messaging chapter in the Progress SonicMQ
Application Programming Guide.

Send Timeout

USE_BROKER_SETTING No setting on the endpoint (the broker setting for this


feature is used). The default setting is USE_BROKER_SETTING.

ON All messages to this endpoint will flow to disk.

OFF No messages to this endpoint will flow to disk.

The time interval, in milliseconds, to attempt to send a message from this endpoint. The
default value is 360000 6 minutes.
5.

98

After you configure the properties, click Apply. The Sonic Management Console
displays the new endpoint in the Endpoints tab.
(You can click Reset to restore the previously applied values before you click Apply.)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Fault Tolerant Connections and Reconnection

If you click Undo, any changes made before the previous Apply are undone. The
information reverts to its previous state and Redo becomes available. (Undo does not
undo the last change unless Apply has been clicked.)

Deleting Progress SonicMQ Endpoints


The following procedure describes how to delete a Progress SonicMQ endpoint.
To delete a Progress SonicMQ endpoint:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, expand the Endpoints folder and click Progress SonicMQ Endpoint.
The upper right panel lists the endpoints in the Endpoints tab.

2.

Select the endpoint you want to delete, and then click Delete.

3.

Confirm the selection. Progress Sonic ESB deletes the selected endpoint.

Fault Tolerant Connections and Reconnection


Progress Sonic ESB provides fault tolerant client connections that allow ESB services to
become failure resistant when used in a replicated broker environment. Enabling fault
tolerant connections allows your ESB services to recover connections without message
loss or duplication in the following circumstances:

Reconnect to the same broker if the connection is lost due to network failure

Reconnect to the same broker through redundant network interfaces if the connection
in lost due to network failure

Reconnect to a broker that is configured as a backup broker if the primary broker fails

Reconnect to a broker that crashes and recovers from the log if that broker is
configured with full broker crash recovery
The fault tolerant and reconnect properties you can set for a connection are:
Connection Parameter

Sonic Management Console


Property

Default Value

faultTolerant

Enable Fault Tolerant Connection

False

initialConnectTimeout

Initial Connect Timeout

30 seconds

faultTolerantReconnectTimeout

Fault Tolerant Reconnect Timeout

60 seconds

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

99

Chapter 3: ESB Endpoints and Connections

Inbound and Outbound Connections


In Progress Sonic ESB, connections are not created until needed. For inbound (entry
endpoint) connections, the connection attempt starts (but does not finish) at service
initialization time. For outbound (exit, fault, and rejected message endpoint (RME))
connections, the connection attempt starts when a service first sends a message over a
given connection. As a result, two connections that have the same URL list might connect
to different brokers in the list. Once a connection is created it can be re-used and can be
shared across multiple sessions within the container. The maximum number of sessions
that share a connection is configurable.

Fault Tolerant Connections


Set the faultTolerant connection parameter to true to enable fault tolerant connections.
When enabled, SonicMQ fault tolerance occurs before the Progress Sonic ESB reconnect
logic is triggered. Only after the SonicMQ client fails to establish or re-establish a
connection using the fault tolerance mechanism will the Progress Sonic ESB reconnect
process start.
To use fault tolerant connections, the broker to which a client connects should be
configured, started, and sychronized as a replication broker or a fully crash recoverable
broker (see Configuring Broker Replication in the Progress SonicMQ Configuration
and Management Guide and Achieving Continuous Availability in the Progress
SonicMQ Deployment Guide for information about using fault tolerant connections and
replication brokers). Otherwise, only the transient network recovery or redundant network
recovery feature can be used at runtime.
Progress recommends that a fault tolerant connection to a replicated broker should specify
primary and backup broker URLs in the URL list. This ensures that both primary and
backup URLs are tried for a successful initial connection. The Connection URL list is
only used when creating the initial connection, not for fault tolerant reconnection
attempts. Fault tolerant reconnection URLs are provided by the broker servicing the ESB
Container at the time a disconnect occurs. See the Configuring Routings chapter in the
Progress SonicMQ Configuration and Management Guide for more information.

100

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Fault Tolerant Connections and Reconnection

Reconnection
Progress Sonic ESB endpoints appear as SonicMQ clients. From the perspective of
SonicMQ, the ESB reconnect implementation is a customized client reconnect
implementation.
Progress Sonic ESB always tries to reconnect when a connection fails, regardless of
whether the faultTolerant connection parameter is set to true or false.
The following sections explain how initial connections are created and how interrupted
connections are reconnected.

Initial Connections
The initialConnectTimeout value specifies for how many seconds an ESB endpoint will
try to establish an initial connection. This value is the total time during which the initial
connection is attempted, not the time spent attempting to connect to each URL. This
means that some URLs in the URL list might not be attempted. For non-fault tolerant
connections, this parameter is ignored and the endpoint tries each URL once.
Note Two special timeout values, 0 and -1, are available in SonicMQ but are not available in

Progress Sonic ESB, where configurations are limited to a value range of 1-3600.
If the SonicMQ initial connection cannot be established within the timeout period, the
Progress Sonic ESB reconnect logic will retry. This retry looks like the initial connection
attempt to the SonicMQ implementation. The retry starts trying to establish connections
again, starting with the first URL in the initial connection list. The Progress Sonic ESB
retry will continue until the container is shut down.

Interrupted Connections
The faultTolerantReconnectTimeout value specifies how many seconds an ESB endpoint
will allow for reconnecting a broken connection to the primary or backup broker using the
fault tolerant mechanism. If the connection is re-established before the timeout expires,
the endpoint will not be connected to a broker outside the original fault tolerant pair.
If the connection is not re-established within the reconnect timeout period, SonicMQ
signals that the connection failed and the Sonic ESB reconnect logic tries to create a new
connection using the initial connection process described previously. In this case, it is
possible that a connection can be established to a broker that is not a member of the
original fault tolerant pair.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

101

Chapter 3: ESB Endpoints and Connections

The Progress Sonic ESB reconnect logic continues to attempt to re-establish an


interrupted connection until the container is shut down. After 20 retries, a delay is inserted
between each retry. The delay increases with each retry to a maximum delay of 30
seconds. Each retry cycles through all the URLs in the connection URL list.
Like the initialConnectTimeout value, the faultTolerantReconnectTimeout value is
limited to a range of 1-3600. The faultTolerantReconnectTimeout value is ignored for
non-fault tolerant connections; an interrupted non-fault tolerant connection will
immediately trigger the Sonic ESB reconnect logic.

Quality of Service
In the case of an interrupted connection, the ESB reconnect creates a new connection and
the connection state is lost. (In a fault tolerant connection, the state is preserved and the
connection never appears interrupted). This behavior has the following impact on QoS:

Best Effort Messages may be lost, no Fault or RME message is guaranteed.

At Least Once If the connection is lost before a message is acknowledged, the


acknowledgement fails, but messages already sent to the Outbox and Fault box are
still processed. A copy of an incoming message that is not acknowledged is sent to
the RME. The unacknowledged message is redelivered to the service (for queues), or
to the durable subscription endpoints (for topics).

Exactly Once If the connection is lost while a message is being processed, a copy
of incoming message is sent to the RME. The message is redelivered to the service
(for queues), or to the durable subscription endpoints (for topics). Messages sent to
the Outbox and Fault box are not processed in this case.

102

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Configuring Connections

Setting the Ping Interval


You can enable or disable sending active pings on a connection by setting the
pingInterval connection property. When used where messages are sent to the endpoint at
a low frequency, the ping can detect a connection drop and trigger reconnect logic to keep
the connection alive. However, when large messages are sent on a slow network, a small
ping interval can cause a response failure that can be interpreted as a connection drop.
Consider the size and frequency of messages that will be sent to the endpoint when setting
this property:

For non-fault tolerant connections, the default pingInterval value is 90 seconds.

For fault tolerant connections, the default pingInterval value is 30 seconds.


Ping interval behavior for fault tolerant connections differs from that of non-fault tolerant
connections in that the ping does not require a response from the broker in fault tolerant
connections. A lack of response from the broker does not result in a connection failure in
this case.

Configuring Connections
Every endpoint has an associated connection. The following procedure describes how to
view existing connections and configure a new connection.
To view connections and configure a connection:
1.

In the ESB Configured Objects section of the Sonic Management Console, expand
the Endpoints folder, then select Progress SonicMQ Endpoint.

2.

In the right panel, click the Connections tab to view available connections.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

103

Chapter 3: ESB Endpoints and Connections

104

3.

Select a connection. The lower right panel displays the properties of the selected
connection, as shown:

4.

Click New. The connection property fields in the Connection Maintenance panel are
cleared. Required properties in the Connection Maintenance and Init Parameters
sections are marked with an asterisk (*).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Configuring Connections
5.

Enter, accept, or select values for the following properties:


Property

Description

Connection Name

A unique, meaningful name.

Connection Type

Accept the required value, Progress SonicMQ Connection.

Connection URLs

One or a comma-delimited list of URLs for the Progress SonicMQ


brokers to make connections are made (in the format
[protocol://]hostname[:port]).

User Name

The user name to authenticate with the Progress SonicMQ broker.

Password

The password to authenticate with the Progress SonicMQ broker.

Login SPI
Classname

Optionally, you can pass the Login SPI classname to the SonicMQ
connection factory.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

105

Chapter 3: ESB Endpoints and Connections


6.

Set the maximum sessions for this connection:


Property

Description

Maximum Receive
Sessions Per
Connection

When configuring a connection, you specify the number of sessions


Progress Sonic ESB creates on an underlying Progress SonicMQ
connection for Progress Sonic ESB entry endpoints:

Unlimited The default for a single connection configuration.

Progress Sonic ESB creates one underlying Progress SonicMQ


connection. All Progress SonicMQ sessions that Progress Sonic
ESB creates for endpoints share that single connection. There is
an unlimited number of receiving Progress SonicMQ sessions per
Progress SonicMQ connection.

Single Progress Sonic ESB creates a dedicated Progress

SonicMQ connection for each Progress SonicMQ session that it


creates for endpoints. There is a single receiving Progress
SonicMQ session per Progress SonicMQ connection. This setting
provides enhanced performance, but results in greater memory
and resource consumption throughput.

Important

106

Maximum
BEST_EFFORT
Sessions

The size of the pool of Progress SonicMQ sessions created for


sending messages at a BEST_EFFORT QoS level. This number should
grow as the number of listeners grows. Specify a numeric value. The
default is 3.

Maximum
AT_LEAST_ONCE
Sessions

The size of the pool of Progress SonicMQ sessions created for


sending messages at an AT_LEAST_ONCE QoS level. This number
should grow as the number of listeners grows. Specify a numeric
value. The default is 3.

Maximum
EXACTLY_ONCE
Sessions

The size of the pool of Progress SonicMQ sessions created for


sending messages at an EXACTLY_ONCE QoS level. This number should
grow as the number of listeners grows. Specify a numeric value. The
default is 3.

Maximum
Web Service
Sessions

The number of pooled sessions that can be used for Web service
invocations. Specify a positive integer value. The default value is 10.

Sonic ESB creates a SonicMQ temporary destination for each pooled session at the
time that each connection is created.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Configuring Connections
7.

Set the ping interval and fault tolerant connection parameters:


Property

Description

Ping Interval

The interval in seconds for sending active pings on the connection.


Specify a numeric value:

The default for non-fault tolerant connections is 90.

The default for fault tolerant connections is 30.

A value of 0 or any negative number disables the ping. See Setting the
Ping Interval on page 103 for more information.
Enable Fault
Tolerant
Connection

Specifies whether to enable fault tolerant connections for the endpoint.


This setting is optional, either True or False; the default is False. See
Fault Tolerant Connections and Reconnection on page 99 for more
information.

Initial Connect
Timeout

The interval in seconds during which a client can try to establish an initial
connection. Specify a numerical value; the default is 30 seconds. See
Fault Tolerant Connections and Reconnection on page 99 for more
information.

Fault Tolerant
Reconnect
Timeout

The interval in seconds that a client will allow for reconnection. Specify
a numerical value; the default is 60 seconds. See Fault Tolerant
Connections and Reconnection on page 99 for more information.

JMS
Connection ID

When a JMS Connection ID is entered ( a non-empty string), fault


tolerant clients can reconnect to a broker before the brokers pending
reconnect timeout is reached. However, taking advantage of this
functionality will not allow multiple, simultaneous JMS connections
using use the same JMS connection ID. See Fault Tolerant Connections
and Reconnection on page 99 for more information.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

107

Chapter 3: ESB Endpoints and Connections


8.

Scroll down in the Connection Maintenance area to set the Secure Socket Layer
(SSL) properties. Set these properties only if you are using certificate-based
authentication:
Property

Description

SSL CA Certificates
Location

Specifies the location of the Certificate Authority (CA) certificate


used to connect to the Progress SonicMQ broker.

SSL Certificate Chain


File

Specifies the pathname that points to the file containing the


Progress SonicMQ broker certificate chain for SSL.

SSL Private Key File

Provides the pathname that points to the file containing the brokerencrypted private key for SSL.

SSL Private Key


Password

Provides the password to encrypt the broker private key for SSL.

SSL Certificate Chain


Form

Specifies the format of the file containing the broker certificate


chain:

PKCS7

PKCS12

LIST

SSL Cipher Suites

The value is a comma-delimited list of all cipher suites, in priority


order, supported by the Progress SonicMQ broker connection. For
broker-client communications the broker that initiates the
connection negotiates to the highest-priority cipher suite they both
support. The default is SSL_RSA_WITH_3DES_EDE_CBC_SHA.

SSL Provider Class

Specifies the Progress SonicMQ adapter class name of the SSL


implementation. The supported adapters are:

progress.message.net.ssl.jsafe.jsafeSSLImpl

(the default)

Note

108

progress.message.net.ssl.jsse.JSSEImpl

For information on the supported cipher suites, see Implementing Security in the Progress
SonicMQ Deployment Guide.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Deleting Progress SonicMQ Connections


9.

After you configure the properties, click Apply. The Sonic Management Console
displays the new connection in the Connections tab.
(You can click Reset to restore the previously applied values before you click Apply.)
If you click Undo, any changes made before the previous Apply are undone. The
information reverts to its previous state and Redo becomes available. (Undo does not
undo the last change unless Apply has been clicked.)

Deleting Progress SonicMQ Connections


The following procedure describes how to delete a Progress SonicMQ connection.
To delete a connection:
1.

In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, expand the Endpoints folder, click the Progress SonicMQ Endpoint
folder.

2.

In the right panel, click the Connections tab. The Sonic Management Console lists
the available connections under the Connections tab.

3.

Select a connection and click Delete.

4.

Confirm the selection. Progress Sonic ESB deletes the connection.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

109

Chapter 3: ESB Endpoints and Connections

110

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 4

Configuring Web Services

This chapter describes how to configure Web Services using WS-* standards in the
following sections:

Overview

Configuring WebService Protocols for ESB Processes

Related Configuration Documentation

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

111

Chapter 4: Configuring Web Services

Overview
Sonic ESB processes can invoke and implement web services that conform to the
WS-Security and WS-ReliableMessaging specifications. To enable this functionality, an
administrator must correctly configure messaging brokers, acceptors, and routings.
Sonic ESB leverages WS-Security and WS-ReliableMessaging support built into
SonicMQ. An overview of how this feature is supported in SonicMQ is described in the
Using HTTP Direct for Web Services chapter of the Progress SonicMQ Deployment
Guide. This chapter discusses the behavior of JMS clients that invoke or implement web
services. The configuration issues are the same for ESB processes as they are for JMS
clients, with one exception regarding the configuration of WebService protocols.

Configuring WebService Protocols for ESB Processes


The configuration of Web service protocols is documented in detail in the Configuring
Acceptors chapter of the Progress SonicMQ Configuration and Management Guide.
This chapter contains a Configuring HTTP(S) Direct Web Service Protocol Handlers
section that describes how to configure Endpoint URLs for web services. This section
refers to the following the dialog box, which is used to configure endpoint URLs:

112

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Related Configuration Documentation

An endpoint URL is used by SOAP/HTTP clients to access a web service implemented


by an ESB process. A URL extension can be mapped to a JMS destination or a URL. If it
is mapped to a URL, the URL must be either a JNDI URL or a sonic URL of the form:
sonic:///node_name/process_name

where node_name is either the literal string local or a valid node name where the process
is deployed.
If you specify the URL of an ESB process, the process must have an entry endpoint and
be deployed in an ESB Container.

Related Configuration Documentation


For more information about configuring Web services, see the following SonicMQ
documents:
Table 3. Configuring SonicMQ for WS-Security and WS-ReliableMessaging

Configurable
Element

Location

HTTP Direct Acceptor


Web Service Protocol

See the Configuring Acceptors chapter of the Progress SonicMQ


Configuration and Management Guide.

HTTP Web Service


Protocol Routing

See the Configuring Routings chapter of the Progress SonicMQ


Configuration and Management Guide.

Broker

See the Configuring SonicMQ Brokers chapter of the Progress


SonicMQ Configuration and Management Guide.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

113

Chapter 4: Configuring Web Services

114

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Part II

Configuring XML Servers

Part II contains the following chapters:

Chapter 5, Monitoring and Logging

Chapter 6, Performance Tuning XML Servers

Chapter 7, Backing Up and Restoring Document Collections

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

115

116

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 5

Monitoring and Logging

Chapter 5 includes the following sections:

Monitoring describes Sonic XML Server metrics and notifications.

Logging describes service-specific information and Sonic XML Server-related


information, including method parameters, inputs, and outputs, and transaction logs.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

117

Chapter 5: Monitoring and Logging

Monitoring
Sonic XML Server monitoring includes metrics and notifications, as described in the
following sections.

Metrics
Sonic XML Server registers metrics with its ESB Container once during service
initialization. The ESB Container then registers these metrics with the management
container. Sonic XML Server metrics are dynamic and can be enabled and disabled by the
ESB Container.
Sonic XML Server provides metrics for:

Document actions:

ArchivedPerMinute

GetsPerMinute

(both from the document collections and the Inbox)


PutsPerMinute (both to the document collections and the Outbox)

RemovesPerMinute

Messages:

Processing actions:

118

Processed
TranslationsPerMinute
XQueriesPerMinute

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Monitoring

The following procedure describes how to enable Sonic XML Server metrics.
To enable XML Service metrics:
1.

Open the Sonic Management Console and select the Manage tab.

2.

Select a running ESB Container containing an XML Service instance.

3.

Right-click on the service-instance name, and select Metrics.... The Monitoring dialog
box opens with its Metrics tab:

4.

Select one metric or a group of metrics (by selecting the parent folder) and select
Enable. The Sonic Management Console enables the metrics you selected, for
example, the entire group of document metrics:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

119

Chapter 5: Monitoring and Logging

If you select an individual metric, more options become available. You can disable the
metric or watch the metric in a Metrics Watcher window in both a bar chart and line
graph, for example:

For information on watching and disabling metrics, as well as general information on


metrics, see the Monitoring chapter in the Progress SonicMQ Configuration and
Management Guide.

120

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Monitoring

Notifications
Notifications are associated with the delivery of event information. The ESB Container
registers Sonic XML Server notifications with the management container. The Sonic
Management Console subscribes to notifications and can display notifications in a Watch
window.
Sonic XML Server provides this notification:

xmlService.invalidArchiveAddress

Notifications from the management containers components include:

system.state.Offline
system.state.Online

The xmlService.invalidArchiveAddress notification is published when a document


collections archive address is invalid at runtime. Its attributes are:

serviceName Name of the XML Service that performed the operation

documentCollectionName Name of the collection on which the operation was


performed

documentName Name of the document being archived when the failure occurred

message Message giving further details of the reason for the failure
The following procedure describes how to monitor notifications.
To monitor notifications:
1.

Open the Sonic Management Console and select the Manage tab.

2.

Select a running ESB Container containing an XML Service instance, right-click on


the service-instance name, and select Notifications... . The Monitoring dialog box
opens with its Notifications tab:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

121

Chapter 5: Monitoring and Logging


3.

You can select one or more notifications, and for each notification, select Watch and
select whether to watch:

By Component (ESB Container)

By Container (management container)

By Domain

The Sonic Management Console marks notifications that are being watched:

The Sonic Management Console opens a Notification Watcher.


For general information on notifications and on watching notifications and viewing
notification attributes, see the Monitoring chapter in the Progress SonicMQ
Configuration and Management Guide.
See also the Progress SonicMQ Administrative Programming Guide and the Progress
Sonic Event Monitor Users Guide documentation for information on other options for
tracking these notifcations.

122

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Logging

Logging
Sonic XML Server sends operational information to container logs. Management
containers send application and status messages to the console and to a log file. ESB
Containers also provide access to a common log file for all the services they host. Fatal
errors are always sent as an exception stack trace to the log and show root causes when
available. The default log file is domainName.containerName.log in the management
containers working directory.
Log information includes:

Service-specific information Includes state changes within the service itself

Sonic XML Server-related information Includes method parameters, inputs,


and outputs
You can turn on internal logging for debugging purposes. Set the Java system property
com.sonicsw.xe.logging on the management container hosting the XML Service. In the
Sonic Management Consoles Manage view, edit the containers Properties and enter
your Java system property settings on its Environment tab, using one or more of the
following:

Script

Script.Actions

Script.Actions.Get

Script.Actions.Put

Script.Actions.Remove

Script.Actions.XQuery

Script.Actions.XSLT

Script.Parser

Management.collections

Management.documents

Collections

Collections.Factory

Collections.Storage

Collections.Storage.Utils

Utils

Utils.XPath

XMLService.message

XMLService.service

Archive

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

123

Chapter 5: Monitoring and Logging

The following screen shows the Environment tab of a management containers


configuration:

Some of these strings are hierarchical, so you can use one setting such as, Script.Actions,
to include others such as, Script.Actions.Get.
For more information on logging, see the Configuring Containers and Collections
chapter and the Managing Containers and Collections chapter in the Progress SonicMQ
Configuration and Management Guide.

124

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 6

Performance Tuning XML Servers

Most users of Sonic XML Server experience high performance without tuning. This
chapter contains suggestions that can optimize your XML Server configuration and
application design for your applications patterns of data access. Because there can be
trade-offs and tuning is highly application-specific, you should test your application to
determine which suggestions are most effective.
This chapter contains the following sections:

Tools for Tuning XML Servers shows where tuning parameters are accessed.

Tuning XML Services and Collections explains transactions and concurrency and
describes how to tune action flows, XML Services, and collections.

Tuning Data Storage contains suggestions for distributing documents, in


collections, determining locations for collections, using message routing, tuning
storage maintenance, and managing the transaction log.

XPath Expressions and XSLT Transformations discusses ways to optimize XPath


and XSLT performance.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

125

Chapter 6: Performance Tuning XML Servers

Tools for Tuning XML Servers


The suggestions and recommendations in this chapter involve several aspects of Sonic
XML Servers. Some are design and operational issues. Others are configuration functions
accessed through the Sonic Management Console connect to the domain that hosts the
XML Services configuration. Three specific tool are used for the settings in this chapter.

126

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tools for Tuning XML Servers

Setting Properties on an XML Service Type Instance


Maintain properties for an XML Service Type instance through the ESB Configured
Objects section of the Sonic Management Console:

For more information about setting properties on a service instance, see ESB Configured
Objects on page 26.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

127

Chapter 6: Performance Tuning XML Servers

Setting Properties on a Component in an ESB Container


Maintain properties for a component in an ESB Container through the ESB Configured
Objects section of the Sonic Management Console:

This figure shows an ESB Container that has added an instance of XMLServiceType.
In this example, the instance shows that it has 5 listeners. The default value is 1.
For more information about maintaining listeners, see Changing the Number of
Listeners on Services in ESB Containers on page 61

128

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tools for Tuning XML Servers

Setting JVM System Properties on a Management Container


Maintain JVM system properties for a management container through the Sonic
Management Console by opening the containers Properties, and then choosing the
Environment tab, as shown:

This illustration show an example of a logging setting, as used in Logging on page 123.
For more information on management containers and their environment settings, see the
Configuring Containers and Collections chapter in the Progress SonicMQ
Configuration and Management Guide.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

129

Chapter 6: Performance Tuning XML Servers

Tuning XML Services and Collections


The following sections discuss update versus read-only transactions, locking vs. nonlocking XML Services, tuning action flows, configuring XML Services and collections,
and managing address space and cache size, and how these impact performance. The first
section provides background information on transactions and concurrency control.

Transactions and Concurrency Control


Each Sonic XML Server contains a transaction scheduler that dynamically balances the
resources required to begin and commit transactions as Sonic XML Server action flows
are executed. Within an XML Service thread, each action flow executes within its own
virtual transaction. This ensures that the data viewed and manipulated by the thread is
correctly isolated from other threads that are executing their own virtual transactions.
A datastore transaction is the actual physical transaction that commits changes in the
datastore; it controls data locking and logging to manage concurrent access by multiple
XML Service threads accessing the same datastore. The transaction scheduler allows
several virtual transactions to execute within a single datastore transaction whenever this
can done without compromising data consistency.
The transaction scheduler ensures that:

A virtual transaction commit operation does not return if any data it accessed or
modified is not fully saved in the datastore through a full datastore transaction
commit.

Different threads that are executing read operations at about the same time can
execute concurrently with minimal thread blocking.

Threads that execute update operations run in exclusive mode. This avoids any
possibility of inconsistency in XML data from update operations in other threads.
This sharing of datastore transactions reduces the relative cost of transaction overhead per
virtual transaction. It also improves response time because less thread synchronization is
required. However, to ensure correct data consistency, it sometimes requires completed
virtual transactions to be blocked until the underlying transaction is committed. This can
increase the response time for the threads that are waiting.
When more than one instance of a Sonic XML Service accesses data within the same
collection, the underlying XML Server concurrency mechanisms ensure transactional
integrity and a consistent data view. This management is performed by a system of lock
coordination among XML Service processes.

130

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning XML Services and Collections

This system provides forward-caching of XML data in Sonic XML Server, independent
of the storage location of the data. In addition, fine-grained fetching and writing of XML
nodes allows XPath access to perform optimally with very large documents.
This system has the following characteristics:

Every XML Service accesses only committed, consistent data, even if many XML
documents and collections are accessed.

When there is no conflict, control of data and locking migrates from the Sonic XML
Server datastore server to the data cache of the Sonic XML Service. XML Services
then runs in-memory with a minimum of network access. In this manner,
simultaneous read access is supported for many XML Services.

When one XML Service updates data that is cached by another XML Service, the two
XML Services collaborate to call back locks, invalidate stale data, and refresh the
cache of all XML Services that are using the data.

Fetching, refreshing, and writing of data is on-demandit is performed only for those
blocks of data actually read or updated by Sonic XML Server. When an update
operation is in progress, an XML Service in locking mode might have to wait for
completion before it can acquire shared data.

In nonlocking mode, the datastore server provides a time-consistent snapshot of data


to one or more read transactions that might execute concurrently with an update
transaction. This eliminates any lock waiting, though it means that read transactions
do not see changes made by the overlapping update transactions.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

131

Chapter 6: Performance Tuning XML Servers

Tuning Action Flows, Transactions, and XML Services


The following suggestions and settings tune action flows, transactions, and XML
services.

Use Short Running Action Flows


Suggestion: Use short-running action flows.
Long-running action flows can increase the time for an XML datastore transaction to
commit. If you must use long-running action flows, route them to a different XML
Service. For example, assuming you have the flow:
a. Run XQUERY on CollectionA
b. Run XSLT on the result of step a.
c. PUT into CollectionB
d. PUT into Outbox
It would be better to have steps a, b, and d in one xaction, and then do step c separately.

Separate Update and Read-only Action Flows


Suggestion: Separate update and read-only action flows to reduce the processing time of
action flows.
Update action flows run in update transactions that block all other action flows routed to
the same XML Service, even those that access a completely different set of documents.
Update transactions must have write access to the XML datastore. Update transactions
can be performed only by XML Services that have a locking concurrency mode. (Update
transactions have a performance cost since they block concurrent transactions.)
Read-only actions can run concurrently, return immediately upon completion, and do not
block until the datastore transaction commit, as long no update actions have run in the
same datastore transaction. In a nonlocking XML Service, this is always true. Read-only
transactions can be performed by XML Services that have either a locking or nonlocking
concurrency mode. Read-only transactions in a nonlocking XML Service do not obtain
read locks on what they read, but read-only transactions in a locking service do obtain
read locks.

132

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning XML Services and Collections

Specify auto select for the Transaction Level


Suggestion: Unless you have a specific reason to obtain a write lock for a read-only action
flow, it is more efficient to specify auto select for your transaction level.
Action flows are either update or read-only and you can specify the transaction level for
an action flow as always update to specify that the action flow is always part of an update
transaction or auto select so that the transaction type is determined by Sonic XML Server
based on the contents of the action.
See the online help in the Sonic Workbench for information about action flows.

Access a Document Collection from One Update XML Service.


Suggestion: Access a document collection from only one update XML Service.
XML Services are configured in the ESB Configured Objects section of the Sonic
Manangent Console as either:

Locking Read-only actions are serialized with respect to update actions running
in the same XML Service.

Nonlocking Read-only actions run concurrently with update actions running in a


locking XML Service.
Every collection must have at least one locking XML Service so documents can be added
and removed. For collections that have update actions run against them frequently, each
collection should have its own locking XML Service. Update operations include PUT into
collection, REMOVE from collection, and management operations such as archiving and
creating collections. The exceptions are GET, XSLT, and XQUERY. Occasionally you can have
XSLT or XQUERY actions that are special java or XIS extensions to modify data, but this
is not relevant except in advanced useage. All other actions are read-only. Updates are the
primary operations involved in tuning an application for concurrent access. Sonic XML
Server locks parent elements of a node that is being updated to guarantee the integrity of
the operation. This can limit access to the document for other updating XML Services.
You should identify any key documents that require update access by many users. You can
then optimize the document structure and routing to XML Services to minimize wait time.
Each collection should have no more than one locking XML Service accessing it to
eliminate lock contention and service delays in response. Having a single locking XML
Service per collection also prevents conflicts that can hamper performance.
You can provide as many nonlocking XML Services per collection as you want without
creating conflicts. Since nonlocking caches are nonblocking, read operations do not have

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

133

Chapter 6: Performance Tuning XML Servers

to wait for update operations to be finished as they do for locking XML Services. This
allows concurrent read operations on the datastore.
When more than one locking XML Service is involved, normal transaction management
introduces the risk of transaction deadlocks. When an XML Service experiences a
deadlock, it retries the transaction. If the retries are unsuccessful, a deadlock exception is
thrown, the input message is rejected and sent to the rejected message endpoint (RME).
A deadlock ends a datastore transaction and all action flows currently active in that XML
Service, including action flows that have completed and action flows waiting for the
XML datastore commit. All of the action flows currently running in the datastore
transaction must then be explicitly restarted by resending the rejected message to the
XML Service. However, retrying a transaction can impact overall system performance.
To change this property, modify the Concurrency Mode setting for the service instance.
See Setting Properties on an XML Service Type Instance on page 127 for more
information.

Perform Read Transactions by Nonlocking XML Services.


Suggestion: Have read transactions performed by nonlocking XML Services.
Transaction concurrency bottlenecks can be drastically reduced by routing requests to
exclusive XML Services or by specifying nonlocking XML Services. Read-only action
flows running in a locking service can be blocked by update action flows or another
service. Therefore, you get better performance by having read transactions performed by
nonlocking services. Action flows running in a nonlocking service instance are never
blocked by update action flows and never have to wait for the XML datastore commit
before returning results to the client.
To change this property, modify the Concurrency Mode setting for the service instance.
See Setting Properties on an XML Service Type Instance on page 127 for more
information.

Configure the Transaction Open Interval and Commit Transaction If Idle


Suggestion: Configure the Transaction Open Interval and Commit Transaction If
Idle XML Service properties for best performance.
Both update and read-only actions can be batched in the same datastore transaction. The
Transaction Open Interval specifies the interval during which Sonic XML Server
schedules action flows to execute within a datastore transaction.

134

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning XML Services and Collections

An XML datastore transaction batch is only open to new action flows until the
Transaction Open Interval elapses. When the interval expires, the XML datastore
transaction commits if there are no active action flows still running in the transaction. An
interval of one to ten seconds is recommended.
Update action flows are always serialized with respect to all other action flows running in
the same XML Service. Update action flows block until the XML datastore transaction
commit. JMS message ordering is not guaranteed, and therefore, the action flows are not
guaranteed to run in any specific order.
Setting Commit Transaction If Idle to true causes the XML Service to commit the
XML datastore transaction before the Transaction Open Interval elapses whenever
there are no action flows waiting to be scheduled. This can result in update actions
returning sooner. However, this also reduces transaction batching and can reduce the
overall service throughput.
To change these properties, modify the Transaction Open Interval value, and toggle its
Commit Transaction if Idle setting. See Setting Properties on an XML Service Type
Instance on page 127 for more information.

Set Multiple Listener Threads on the ESB Container


Suggestion: Configure an XML Service to use multiple listener threads per ESB
Container.
The number of listener threads is specified when an XML Service is deployed in an ESB
Container. Set the number of listener threads to correspond to the number of requests that
can be serviced within the Transaction Open Interval.
The normal range of listener threads is 1-30 threads. Adding additional listener threads
above the 1 specified by default can significantly improve performance. A range of 15-20
listener threads per XML Service is recommended for the average configuration. This
allows multiple action flows to be batched into XML datastore transactions, and spread
the overhead of XML datastore commits over multiple action flows. A value higher than
20 threads provides only marginal improvement in performance.
To change this setting, modify the Listeners on a service instance deployed in an ESB
Container. See Setting Properties on a Component in an ESB Container on page 128 for
more information.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

135

Chapter 6: Performance Tuning XML Servers

Tuning XML Service Resources


Each XML Service instance has the following resources:

Address space Mapped from the virtual memory range reserved for Sonic XML
Server at startup. This allows XML Server to identify and reference XML nodes and
metadata without having to allocate memory or fetch data.

Data cache Allocated within virtual memory and used to retain XML documents
in memory across operations and transactions.

Network connections To the XML Server lock manager and datastore server.
Collection data for each XML Service is retained in memory on a most recently used
basis. Ensure that the size of the cache can comfortably hold the XML nodes and indexes
that are repeatedly accessed. Also ensure that there is enough RAM on the system to
accommodate the XML Services. Otherwise, the standard virtual memory facilities of the
system start swapping, which eliminates many of the benefits of caching.
The following settings describe how you can tune address space size, cache size, and
cache space affinity to optimize cache performance.

Tune the Address Space Size


Suggestion: Adjust the XML Service Address Space Size configuration property.
The address space size specifies the size of the region of virtual memory that is reserved
for in-memory representation of the XML Server datastore. The maximum size of this
regions depends on how virtual memory, swap space, and heap allocation are managed by
the operating system.
Address space is reserved by Sonic XML Server in chunks of 64KB and can be as much
as one gigabyte, if needed. Address space reserved for an XML Service is not available
to other applications or the operating system. The overall performance cost of managing
it is relatively small. The cost consists of CPU time to remap address locations that are
used to reference XML documents, indexes, and metadata.
Each running XML Service has a fixed amount of address space. This space is consumed
as indexes or collections are traversed within a transaction, and then released after
garbage collection, which happens in the background after the transaction commits. By
deferring the recycling of address space, XML Server helps increase the chances of hot
traversal to those pages that are cached in memory and still have all addresses correctly
mapped.

136

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning XML Services and Collections

Some transactions, such as adding an index to a large collection, automatically release


address space in the middle of an operation. For certain unoptimized queries and for very
long transactions, however, address space is progressively consumed during the
transaction until the transaction is committed. In the worst case, the configured address
space size is exhausted and a restartable exception is thrown. There are several ways you
can avoid this:

Increase the amount of address space allocated to the XML Service when you
configure it in the Sonic Management Console.

Add indexes to optimize queries and avoid lengthy sequential searches.


For key operations, including creation of indexes and insertion into collections, XML
Server dynamically releases address space during execution. This allows a single request
to perform the operation even when the total amount of data managed exceeds the
configured address space limit.
To change this property, modify the Address Space Size setting for the service instance.
See Setting Properties on an XML Service Type Instance on page 127 for more
information.
In rare cases, you might want to tune the internal trigger points for this address space
release by setting the following environment variables for the container hosting the XML
Service:

XLN_INDEX_NODE_COUNT_AS_RELEASE controls how often address space is released as


you create an index on a large collection (the default is 20,000 nodes).

XLN_DIR_ENTRY_COUNT_AS_RELEASE controls address space release when deleting


documents (the default is every 100 files deleted).
To set these environment variables, use the Sonic Management Consoles Manage view
to edit the containers Properties and enter your settings on its Environment tab, as
illustrated on page 124. For more information about environment settings, see the
Configuring Containers and Collections chapter in the Progress SonicMQ
Configuration and Management Guide.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

137

Chapter 6: Performance Tuning XML Servers

Adjust Cache Size


Suggestion: Adjust the XML Service cache size (specified by the Cache Size XML
Service configuration property.
Performance for updates and queries is sensitive to cache size. To determine the optimum
cache size for your application, try to minimize the number of times the client must swap
pages out of the cache and send them back to the server. Consider the following factors:

Amount of data that is accessed XML Services that are accessing or updating
large amounts of data need larger caches.

Amount of physical memory on a machine Usually, it is desirable for the cache


to stay in physical memory rather than to be swapped out to disk.

Data access patterns A large datastore of documents might have a relatively small
number of documents that are regularly returned from queries or updated and might
not require as large a cache.
To change this property, modify the Cache Size setting for the service instance.
See Setting Properties on an XML Service Type Instance on page 127 for more
information.

Take Advantage of Cache Affinity


When queries access documents that have already been retrieved and cached, query speed
is improved. Grouping documents in collections so that queries retrieve cached data can
enhance performance.
For Progress Sonic ESB clients, a high level of cache affinity is ensured by routing
requests to XML Service instances that are appropriately specialized in designated areas
of the storage hierarchy.
Cache affinity describes the degree to which data accessed within a program overlaps with
data already retrieved on behalf of a previous request. Where there is high cache affinity,
strong cache management architectures such as XML Server have a relative performance
advantage.
For an XML Service, the effectiveness of cache affinity has three levels:

Cold access A request accesses XML documents that have not been retrieved
recently by this XML Service, or have been called back for another XML Service to
update. The data must be retrieved from the datastore server and possibly from disk
storage. (A fair amount of disk file caching occurs on the server side.) Cold access is
typical of random queries against a collection.

138

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning XML Services and Collections

Warm access The request involves data that has been retrieved by a prior
transaction and is still within the XML Servers data cache, but requires remapping
of address space prior to use. Warm access is typical when:

A user executes consecutive XPath expressions, XSL transformations, and update


operations against the same document.

Successful routing rules funnel a large number of requests for a modest-size


directory to a single XML Service instance.
Hot access Required data has already been accessed in the current transaction, and
can be immediately used without any fetching or mapping of data.

It is typical to single out collections with a high query load, and assign each to its own
read-only cache.

Tuning Collections
Suggestions for tuning collections involve document size and use of indexes.

Tune Document Sizes


Suggestion: Tune the size of documents in collections.
Document size can affect the time it takes to load a document, insert it into a collection,
and perform a nonindexed query. The persistent representation of an XML document can
be up to 2.5 times greater in size than the original XML document. This occurs because
the parsed format of a document is optimized for speed of access as opposed to size. Keep
this in mind when you are planning the storage capacity of your system. In addition, large
documents allow less flexibility when assigning data to collections.
Select the Strip Whitespace option when you configure the collection to decrease
document storage size and searching time. (For more information, see the Progress Sonic
ESB Product Family Developers Guide in the Eclipse help.) Whitespace can
significantly add to the size of a persistent document. This increases memory use and I/O
time. (The XML standard requires a text node to be fully represented, even if it contains
only white space.) Appropriate whitespace formatting can easily be reintroduced to the
document through an XSL transformation.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

139

Chapter 6: Performance Tuning XML Servers

Index Large Collections


Suggestion: Define indexes for large collections.
You should evaluate the need for an index before creating one. indexes speed certain
queries by narrowing the number of documents in the collection being queried. However,
indexes also require substantial resources for update and maintenance. Do not define an
index unless you are confident that the index can minimize the number of documents
traversed in searching a collection. Generally, you define indexes only for queries that
must search large quantities of data.
Indexes are most useful when they are defined by the most selective criteria possible. For
example, if you are searching for a person, it is more effective to index on surname than
gender. Similarly, if you are searching for a location, it is more effective to index by
Zipcode than by State.

Tuning Data Storage


The following sections contain suggestions on distributing documents, determining
locations for collections, message routing, and tuning storage maintenance.

Distributing Documents in Collections


For large data sets (greater than 100 MB), consider distributing the XML documents into
separate collections.
How you distribute your documents and collections can have a significant effect on the
speed of queries and transformations. For example, if you have a DepartmentsCollection,
and most of your use cases access the document collection by product category, you can
distribute your documents based on category (for example, PurchasingCollection,
AccountingCollection, and SalesCollection) and have each category updated by a
separate XML Service.
You can have an XQUERY that searches over multiple collections when you need get data
that might be in more than one collection.

140

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning Data Storage

Message Routing
You can use the Sonic ESB Content-based Routing (CBR) service to route messages to
the appropriate service instance for a document collection. You can define CBR routing
rules to meet a broad range of scalability and concurrent access requirements. (For
information on the CBR service, see Implementing a Content-based Routing Service in
the Progress Sonic ESB Product Family: Developers Guide in the Eclipse help.)
When you configure services, first identify groups of documents that are accessed
independently of each other. Then organize each such set in its own collection. For
example, different kinds of insurance policies could be organized into separate
collections. Each collection could then be used to define a CBR routing rule that routes
relevant read or update operations to a relatively specialized XML Service instance.
The primary goal is to route requests so that only one XML Service is updating a given
collection. The next priority is to subdivide the work among XML Services so that the
load is balanced. Each cache should have an opportunity to hold a substantial part of its
subset in memory.
When you route requests to a nonlocking, read-only XML Service, you can optimize
queries that overlap in the document elements, indexes, or stylesheets they access.
Because the operations in a nonlocking service are insulated from recent and concurrent
update operations, it is possible that the data they retrieve is slightly out of date. The
administrator can control how out of date this view can become by adjusting the
Transaction Open Interval for the service.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

141

Chapter 6: Performance Tuning XML Servers

The following figure shows messages being routed by content to one or more XML
Service instances:
Use Case

Collection

Service Use

XSLT
50 operations/min

Customers

Read-only
Service

PUT
20 operations/min

Retail
Update
Service

PUT
2 operations/min

Wholesale

XQUERY
2000 operations/min

Policies

Read-only
Services

PUT
400 operations/min

Car

Update
Service

PUT
10 operations/min

Home
Update
Service

PUT
20 operations/min

Life

The Read-only Services for Policies represents multiple service instances with many
listener threads and in separate containers.

142

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning Data Storage

Locations for Collection


Typically, a system administrator focuses on collections, and how they relate to actual
disks and files on the network. The administrator:

Defines XML Services to manage the use of disk space on various hosts

Allocates collections for those services based on the expected size and growth factors
for the collections.
Storage decisions are often driven by hardware reliability and recovery concerns. In some
cases, an administrator can improve performance and scalability by the following actions:

Move the XML Server transaction log to an isolated disk with optimal sequential
write performance if applications are update-intensive. (see Managing the
Transaction Log on page 145).

Put collections on fast, defragmented disks and try to balance the disk load for
databases, flat files, and the XML Server transaction log across different physical disk
devices.

Locate collections on the same host as the XML Service to improve the XML retrieval
performance for those service instances. (The datastore server is tuned to use fast,
shared-memory, data transfer when it is on the same machine as the service instance.)
The relative improvement for updating caches is smaller because commit
performance is gated by disk write speed.

Manage the number of collections. Each collection requires some metadata that is
managed by the datastore server. Small collections (less than 1 MB) require the same
schema/storage metadata and server management overhead as larger ones.

Locate XML Services on more than one host to add additional datastore servers (For
more information, see the Progress Sonic ESB Product Family Developers Guide in
the Eclipse help.). This increases the maximum throughput achievable for updateintensive applications, because disk write operations can be distributed across
multiple transaction logs. However, it is uncommon for datastore servers to create
performance bottlenecks.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

143

Chapter 6: Performance Tuning XML Servers

Tuning Storage Maintenance


The following are suggestions for scheduling tasks, backup, and compression to tune
storage.

Do Maintenance on Collections
Suggestion: Perform maintenance on collections for peak efficiency.
Maintaining collections efficiently decreases the number of documents that queries must
search through and also decreases the number of out of date results returned. There are
two ways to maintain collection size:

Manually removing documents

Archiving documents

Compress Collections
Suggestion: Compress collections through backup and restore.
In a collection, Sonic XML Server organizes documents within internal directories that
contain a thousand documents per directory. When documents are removed through timeto-live or are deleted by a DELETE action they are removed from the directory but not
replaced. New documents are added to new directories, not old directories. Older
directories will not contain the maximum number of documents. Therefore, collections
that are subject to frequent document removal take up slightly more space per document
than those that do not have frequent document removal.

Schedule Intensive Operations


Suggestion: Schedule intensive operations in off-peak hours.
Since all update intensive operations affect concurrency, delete operations are optimally
performed in off peak hours. The same is true of documents removed from collections
through the time-to-live (TTL) feature. Delete operations in a collection are often less
time sensitive than updates or queries.
It is possible to perform maintenance at a scheduled time every day. The time when it is
performed depends on the time when the XML Service was started. (You can use
Activation Daemons to schedule these operations. See Using Activation Daemons on
page 78 for information on Activation Daemons.)

144

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Tuning Data Storage

However, there is still a requirement to clean out or archive old data in a way that ensures
continuous, scalable operation. Persistent XML can have many dependencies with
indexes and storage structure. XML Server traverses every node within a document you
are deleting. Deletion time scales with the total number of nodes deleted, plus the number
of index entries that must be removed.
You can also delete an entire collection in the Sonic Management Console without going
through these fine-grained operations. (For more information, see the Progress Sonic ESB
Product Family Developers Guide in the Eclipse help.)

Archive Documents
Suggestion: Regular archiving of documents improves query speed.
Query speed improves when there are fewer documents for unindexed queries to search
through. The time-to-live feature can be used to automatically archive documents. For
more information, see the Progress Sonic ESB Product Family Developers Guide in the
Eclipse help.

Managing the Transaction Log


The transaction log, sonicxmlserver_install_dir\XMLDatabase\etc.log, is a binary log
file that contains all transactions that have not yet been propagated to the XML data stores.
Do not modify or delete this file.
The transaction log can grow and affect performance. Moving the transaction log to an
isolated disk with optimal sequential write performance can improve overall
performance.
Important If you decide to relocate the transaction log, contact Sonic Technical Support for

information on how to do this safely.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

145

Chapter 6: Performance Tuning XML Servers

XPath Expressions and XSLT Transformations


The Progress Sonic ESB Product Family: Developers Guide in the Eclipse help
describes how to use XQuery and XSLT with Sonic XML Server. Both XSLT stylesheets
and XQuery expressions include XPath expressions, and the performance of XPath
expressions is an important part of overall XSLT or XQuery performance. For this reason,
most of the suggestions offered for XPath optimization can be used for both XSLT and
XQuery actions.

XPath Expressions
Improving XPath performance begins with an analysis of application use cases that
retrieve stored XML through XPath expressions. When you have a clear sense of the
patterns of access, including relative size and frequency of XPath retrieval for specific
XML nodes, you can identify areas for optimization.
XPath expressions in XML Server are processed dynamically as they are passed to the
XML Server XPath processor. The performance achieved when a given XPath request is
executed depends on several factors:

Time required to evaluate and optimize the XPath expression

Efficiency of the optimized XPath execution tree, which in turn depends on:

Number of XML elements reachable from the target document

Use of indexes to optimize query constraints

XML Server caching of documents and indexes

Data extraction, sorting, and serialization that must be done on the return set
The following suuggestions can improve XPath performance.

Match Indexes to Queries


Suggestion: Design indexes to match queries as closely as possible.
Sonic XML Server uses a value index, which locates all of the nodes that share:

A common ancestor element

A specified XPath key path

Matching text or floating-point data value for nodes matching that key path

146

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

XPath Expressions and XSLT Transformations

A value index can quickly compute the subset of nodes that match an XPath predicate.
The more closely the XPath expression matches an existing value index, the more certain
you are that the XPath processor can pick up the index in optimization.
Indexing is not required in all situations. Unlike most XML/RDBMS solutions, XML
Server retains the XML DOM structure within storage. This means that many XPath
operations involve simple in-memory DOM traversals that execute extremely fast, even
without an index. Retrieving child nodes from an element or locating parent nodes occurs
at in-memory speeds and does not require indexing. However, selecting a small set of
XML nodes from a large document or collection can be greatly enhanced with appropriate
indexing.
For example:
//Enterprise/personnelData/[lastName=Smith]
collection(foo) //a/b[c=Fred]
INDEX on collection foo
INDEX path = //a/b
Key path =c

Control Results Set Size


Suggestion: Control the XPath result set size.
The data returned by an XPath expression is well defined by the XPath string and the
DOM structure of the document being queried. The size of the results has an important
impact on XPath performance because:

All child nodes included in the result must be explicitly retrieved from the collection.
Address space reserved for returned nodes cannot be dynamically released during the
transaction, eventually limiting the size of the return set.

If the operation returns an XML string, all tags and text data must be accumulated in
an in-memory buffer.

The amount of work required by the application to process results is generally


proportional to their size.

Analyze Whether Excess Nodes Are Returned.


Suggestion: Analyze the nodes to be returned.
The best way to control result set size is to examine the XPath expression to confirm that
all the nodes returned are required by the application. For example, if you want only the
authors of books with a certain title:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

147

Chapter 6: Performance Tuning XML Servers

The query, collection("bookstore")//book[title = "On Walden Pond"], is too broad


because it returns all book information, not just the authors.
The query, collection("bookstore")//book/author[../Title = On Walden Pond],
returns only author elements, but it requires the query engine to check for a title match
for each author.
The query, collection,("bookstore")//book[title = "On Walden Pond"]/author,
immediately selects the correct books, and then returns only the author information.

XSLT Transformations
XSLT stylesheets transform XML documents into another schema. For example, another
dialect of XML for business process integration. XSLT performs this operation on
demand within XML Server, and makes the result accessible to the action flow. You can
optionally return the output or save it in a collection.
In general, the time required to complete a transformation is a function of the size of the
input document and the complexity of the XSLT stylesheet. The steps in XSLT processing
include:
1.

Preprocess the XSLT file to create an optimized stylesheet.

2.

Select nodes from the XML source document, based on the XPath expressions
specified in the XSLT selection syntax. (Some XPath query optimization occurs here,
as discussed previously.)

3.

Match selected nodes against the patterns in the XSLT templates.

4.

Generate the output document.

The optimized stylesheet object is a transient structure that resides on the server only for
the lifetime of the current transaction.
The following suuggestions can improve XSLT performance.

XSLT Node Selection


Suggestion: Narrow the result set passed to the transformation engine
Selection of the input source is important for efficient transformation. To the degree you
narrow the result set passed to the transformation engine, you reduce the time consumed
in pattern matching and generation. Examine the query statements in your XSLT
stylesheet to restrict the number and size of the XML nodes returned to the smallest
workable set.
148

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

XPath Expressions and XSLT Transformations

XSLT Template Matching


Suggestion: Perform filtering in the selection expression rather than the template
matching expression
Depending on the complexity of the XSLT stylesheet, matching the XPath expression of
the template to the selected source data can require intensive computing. You should try
to ensure that any filtering that must be done is achieved in the selection XPath expression
rather than in the template matching XPath expression.
Suggestion: Make XSLT template matching as straightforward as possible.
Use simple XPath expressions that can achieve node comparisons without requiring a lot
of node traversal. Try to avoid recursive XSLT pattern matching. Additional information
about tuning XPath expressions is available in XPath Expressions and XSLT
Transformations on page 146.

XSLT Output Generation


Generating the output document tends to demonstrate predictable, scalable performance.
If the output is stored within Sonic XML Server, rather than in subsequent script actions
or returned from scripts, consider that:

Generating the output takes longer because of XML Server DOM calls that are
required to construct the document.

Subsequent updates and queries should generally perform better because of XML
Server caching.

The application is responsible for synchronizing any changes, that is, regenerating the
output document if any of the inputs have changed significantly.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

149

Chapter 6: Performance Tuning XML Servers

150

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 7

Backing Up and Restoring Document


Collections

The Progress Sonic XML Server backup and restore utilities provide protection from
unintended data corruption or data loss. These utilities support full and incremental
backup and restoration of document collections.
Chapter 7 describes these utilities in the following sections:

Backing Up Sonic XML Server Document Collections describes how to perform


full and incremental backups of Sonic XML Server document collections.

Restoring Sonic XML Server Document Collections describes how to restore Sonic
XML Server document collections.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

151

Chapter 7: Backing Up and Restoring Document Collections

Backing Up Sonic XML Server Document Collections


To implement backup procedures for the Sonic XML Server document collections at your
site, you can use a combination of backup operations:

Full backup Backs up specified XML document collections.

Incremental backup For given XML document collections, backs up all


documents that changed since the last full backup or incremental backup at a lower
level.
To design and implement a backup routine for your site, follow these steps:
1.

Design a backup schedule. See Designing a Backup Schedule on page 152.

2.

Choose locations for backup-related files. See Files Generated by the Backup and
Restore Utilities on page 155.

3.

Make a full backup. See Performing Full Backup on page 157.

4.

For each subsequent day in the backup schedule, perform the backup operation for
that day. See Performing Full Backup on page 157 and Performing Incremental
Backup on page 158.

Designing a Backup Schedule


Incremental backup can reduce the amount of data that needs to be backed up, particularly
for Sonic XML Server document collections with a relatively small number of
modifications. Note that using incremental backup can increase the time required for
restoring the XML data stores.
A typical backup schedule assigns backup operations to each day of the week. For each
incremental backup operation, it specifies the backup level to use. To follow the schedule,
you must perform, for each day of the week, the operations assigned to that day.
You should perform each days backup operations during a low traffic time period, that is,
a time period during which there is relatively little access to the Sonic XML Server
document collections being backed up.
Level 0 specifies a full backup. You specify a backup level from 1 to 9 for each
incremental backup. Documents modified since the last backup at a lower level are copied
to the backup image.

152

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Backing Up Sonic XML Server Document Collections

You can specify XML document collections that were modified since the last backup at a
lower level be copied to the backup image. For example, you could perform a level 2
backup on Monday, followed by a level 4 backup on Tuesday. A subsequent level 3
backup on Wednesday would contain all XML documents modified or added since the
level 2 (Monday) backup.
To perform incremental backups, you must consider what levels to use, and when to back
up at each level. Consider:

Amount of data backed up Increasing the backup level from one day to another
can decrease the amount of data that must be backed up.

Complexity of restoring Increasing the backup level from one day to another can
increase the number of backup images that must be restored.
The following examples show two different backup schedules:

The schedule in Table 4 consists of a full backup on Sunday, and an incremental


backup every subsequent day of the week that backs up every directory that has
changed since the previous days backup. This strategy can result in the backing up
of less data for a given week. But restoration can be more complex than with the
schedule in Table 5. Restoration to Friday, for example, requires the restoration of the
images from Sunday through Friday (six images in all).
:

Table 4. Sample Backup Schedule with Daily Increments

Day

Level

Description

Sunday

0 (full)

Full backup of all specified Sonic XML Server document


collections

Monday

Back up all documents that changed since Sunday

Tuesday

Back up all documents that changed since Monday

Wednesday

Back up all documents that changed since Tuesday

Thursday

Back up all documents that changed since Wednesday

Friday

Back up all documents that changed since Thursday

Saturday

Back up all documents that changed since Friday

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

153

Chapter 7: Backing Up and Restoring Document Collections

The schedule in Table 5 consists of a full backup every Sunday, followed by


incremental backups Monday through Wednesday. These include documents that
changed since Sunday. They are followed by incremental backups Thursday through
Saturday that back up directories that have changed since Wednesday. This strategy
can result in backing up more data in a given week. But restoration is simpler than
with the first schedule. Restoration to Friday, for example, requires the restoration of
images from Friday, Wednesday, and Sunday (three images in all).
Table 5. Sample Backup Schedule with Biweekly Increments

154

Day

Level

Description

Sunday

0 (full)

Full backup of all specified Sonic XML Server document


collections

Monday

Back up all documents that changed since Sunday

Tuesday

Back up all documents that changed since Sunday

Wednesday

Back up all documents that changed since Sunday

Thursday

Back up all documents that changed since Wednesday

Friday

Back up all documents that changed since Wednesday

Saturday

Back up all documents that changed since Wednesday

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Backing Up Sonic XML Server Document Collections

Files Generated by the Backup and Restore Utilities


Sonic XML Servers backup utility generates or updates the following types of files:

Backup image files Images of documents in the Sonic XML Server document
collections backed up. You specify a path name for the directory to contain the image
files when you perform a full or incremental backup.

Backup record file Internally used information about the backup operations that
have been performed. When you perform a full or incremental backup, you specify a
path name for the record file. The filename should have the file extension, .irf. A
backup operation creates the record file if it does not exist; otherwise it modifies the
existing record file. When you perform an incremental backup, the record file must
be the same file that served as the record file for the associated full backup.

Log files The backup and restore utilities create log files in the current directory
with information about the result of the operations. The log file contents are also sent
to the console. The log files are removed, if present, at the beginning of the
backup/restore script. Therefore, running the tools a second time deletes the logs
from the first run.
Be sure that the following is true for both the image file and record file:

These files should be stored on a separate device from the Sonic XML Server
document collections being backed up and from the transaction log. This protects you
in the event of disk crash. It also allows reads to occur on the source disk and writes
on the target disk, which results in a faster backup.

These files must be stored on a device that contains sufficient space. The image files
can require several times the space occupied by the document collections being
backed up. If you use full backup on every nth day and incremental backup on all
other days, and if all document collections of all documents change each day, then the
backup image files will need about n times the size of the data stores being backed up.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

155

Chapter 7: Backing Up and Restoring Document Collections

Using the Backup Utility


The Sonic XML Server backup utility is invoked by a batch file, backup.bat, on Windows
and a shell script, backup.sh, on UNIX.
Entering backup in a console in the sonicxmlserver_install_dir\bin directory without
options prints a usage message:
backup [-all | ([-meta] [-service <servicename>]
[-coll <collectionname>]) [-path <metadatapath>] [-verbose]
[-level <inc-level>] [-incfile <inc-file>] -dir <backupdir>

Command line options can be abbreviated to their first letter, for example -v for -verbose.
Square brackets indicate optional switches.
Table 6 lists the arguments for the backup utility.
Table 6. Backup Utility Arguments

156

Argument

Description

-all

Back up all document collections and metadata in the installation. An


installation is defined by a metadata location.

-meta

Back up only configuration metadata.

-service servicename

Back up all document collections created by the specified service


instance.

-coll collectionname

Back up one, specified document collection.

-path metadatapath

Path to the metadata store, if it is not the default location.

-verbose

Verbose output.

-level inc-level

Incremental backup level, an integer from 0 to 9. The default is 0, a


full backup.

-incfile inc-file

Incremental backup record data file.

-dir backupdir

Directory for backup data. (Required.)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Backing Up Sonic XML Server Document Collections

Performing Full Backup


When performing a backup, the target directory (E:\BU1.1.02 in the following examples)
must not already contain any backups of the Sonic XML Server document collections that
need to be backed up. Use a different directory from the previous run of backup, unless
the backup images from previous runs have been moved. In the following examples, the
-level option specifies level 0, a full backup.
The following command performs a full backup of all Sonic XML Server document
collections for a service named service1. It generates the backup record file,
E:\BU1.1.02\service1.irf, and generates an image file in the directory, E:\BU1.1.02.
backup -service service1 -incfile E:\BU1.1.02\service1.irf -level 0
-dir E:\BU1.1.02

The following command performs a full backup of the configuration metadata. It updates
the backup record file, E:\BU1.1.02\service1.irf, and generates image files in the
directory, E:\BU1.1.02.
backup -meta -incfile E:\BU1.1.02\service1.irf -level 0 -dir E:\BU1.1.02

The following command performs a full backup of all XML data stores in the current
installation.
backup -all -incfile E:\BU1.1.02\service1.irf -incfile 0 -dir E:\BU1.1.02

The following command performs a full backup of the document collection named
employee.
backup -coll employee -incfile E:\BU1.1.02\service1.irf -level 0
-dir E:\BU1.1.02

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

157

Chapter 7: Backing Up and Restoring Document Collections

Performing Incremental Backup


Performing incremental backup is like performing full backup, except that you specify a
nonzero level with the -level option, for example:
backup -service service1 -incfile E:\BU1.1.02\service1.irf -level 2
-dir E:\BU1.2.02

backup -meta -incfile E:\BU1.1.02\service1.irf -level 2 -dir E:\BU1.2.02

When you perform incremental backup, the backup record file that you specify with the
-i option must be the same file that served as backup record file for the associated full
backup.

Restoring Sonic XML Server Document Collections


The restore utility restores Sonic XML Server document collections from a backup
image, restoring either the entire backup set or selected document collections within the
set.
Procedures vary based on whether you are restoring a full or incremental backup:

If you performed full backup, restore the document collections from the latest full
backup images made prior to the time to which you want to restore. (See Restoring
from Full Backup Images on page 160.)

If you performed incremental backup, restore from the relevant incremental backup
images. (See Restoring from Incremental Backup Images on page 161.)
Important To restore a document collection that was removed, you must also restore the metadata

by using -meta and -coll. Using -coll alone is not sufficient.

158

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Restoring Sonic XML Server Document Collections

Using the Restore Utility


The Sonic XML Server restore utility is invoked by a batch file, restore.bat, on
Windows and a shell script, restore.sh, on UNIX. The script is located in the bin
directory of the installation. Entering restore in a console in the
sonicxmlserver_install_dir\bin directory without options prints a usage message:
restore [-all | ([-meta] [-service <servicename>]
[-coll <collectionname>]) [-path <metadatapath>]
[-remap] [-verbose] -dir <datadir>

Command line options can be abbreviated to their first letter, for example -v for -verbose.
Square brackets indicate optional switches.
Table 7 lists the arguments for the restore utility.
Table 7. Restore Utility Arguments

Argument

Description

-all

Restore all document collections and metadata in the installation. An


installation is defined by a metadata location.

-meta

Restore only configuration metadata.

-service servicename

Restore all document collections for the specified service instance.

-coll collectionname

Restore one, specified document collection.

-path metadatapath

Path to the metadata store to write to if you want to restore to a


different metadata location than the backup destination.

-remap

Perform interactive remapping of host/directory for services. Also


use the -path metadatapath option to restore the metadata as well.

-verbose

Verbose output.

-dir backupdir

Directory containing backup data (required).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

159

Chapter 7: Backing Up and Restoring Document Collections

Restoring from Full Backup Images


To restore from full backup images, use the restore utility and specify the following:

Document collections to restore

Directory containing the backup images of the document collections to restore. These
are the images that are generated by backup when you perform full backup.
The following example restores all the backup images contained in the directory,
E:\BU1.1.02.
restore -all -dir E:\BU1.1.02

If you restore to a different host, use the remap option along with the service or -coll
option instead of the all option. Otherwise, if you run backup using the -all option on
host A and then restore on host B, restore restores the metadata and points to the original
document collections on the host A. This results in both installations pointing to the same
document collections. Changes made to the document collections in either installation are
recorded in the same document collections on host A.
Important The remap option works only when backup and restore are used on the same platform.

To restore both the collections and the metadata to a new location, you must use both
-remap and -path (to remap the location of the metadata).
The following example restores all backup images of Sonic XML Server document
collections created by service1 contained in the directory, E:\BU1.1.02.
restore -service service1 -dir E:\BU1.1.02

160

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Restoring Sonic XML Server Document Collections

Restoring from Incremental Backup Images


To restore from incremental backup images from a given day, use the restore utility and
specify:

Document collections to restore. These must be document collections that you


restored from full backup images.

Directory containing the backup images of the document collections to restore. These
are the images that were generated by backup when you performed incremental
backup on the given day.
To determine which days backup images to restore, construct a list of days:
1.

Identify the day to which you want to restore on the list.

2.

Consider each day that is earlier than the day to which you want to restore and later
than the latest prior full backup. Consider each such day in reverse order, from latest
to earliest. For each such day, if its backup level is lower than the backup level of the
lists last day, add the day to the end of the list.

Restore the images from each day on the list, working in reverse order, starting with the
last day on the list. For example, you could perform the following backups:
1.

Full backup on Monday

2.

Level 5 on Tuesday

3.

Level 6 on Wednesday

4.

Level 2 on Thursday

5.

Level 4 on Friday

To restore to Friday, start by putting Friday on the list. Then consider each previous day,
Thursday, Wednesday, and Tuesday. Thursdays level is lower than Fridays level, so
Thursday goes on the list. Wednesdays level is not lower than Thursdays level, so it does
not go on the list. Finally, Tuesdays level is not lower than Thursdays level, so it does
not go on the list either. The final list is: Friday, Thursday. So, after restoring from full
backup images, you should restore from Thursdays images, and then restore from
Fridays images.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

161

Chapter 7: Backing Up and Restoring Document Collections

162

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Part III

Configuring Database Services

Part III contains the following chapters:

Chapter 8, Using the Database Service JDBC Drivers

Chapter 9, Driver Connection Properties and Data Types by Database Brand

Chapter 10, SQL Escape Sequences for JDBC

Chapter 11, Configuring SQL Server Windows Authentication


Note This section provides information for the JDBC drivers bundled with Progress Sonic

Database Service. If your installation uses a different JDBC Driver, consult the vendors
documentation for their configuration guidelines.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

163

164

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 8

Using the Database Service JDBC Drivers

Chapter 8 includes information on failover, load balancing, and error handling for
Progress Sonic Database Service connections. This chapter includes the following
sections:

JDBC Driver Connection Properties and the Database Service Explains how to
configure and deploy third-party JDBC drivers for use with Sonic Database Service.

Load Balancing, Failover, and Connection Retry Explains how these features are
implemented and provides references to appendixes where the connection properties
for each of the JDBC drivers are listed.

Using Activation Daemons Shows how to use Activation Daemons with


Database Services.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

165

Chapter 8: Using the Database Service JDBC Drivers

JDBC Driver Connection Properties and the Database


Service
The Database Service reconnect timeout might expire while the JDBC driver failover or
retry is taking place. In this event, if the JDBC driver failover or connection retry
operations exceed the Database Service connection Timeout limit, the connection will not
succeed and the associated Database Service operation will fail, resulting in an error
message being sent to the rejected message endpoint (RME.)
The Database Service reconnect is not the same as the JDBC driver connection retry. The
Database Service is not aware of a connection failure until the JDBC driver connection
retry is unsuccessful. When the Database Service attempts a reconnection, the JDBC
driver acts as if this is a new database connection and the driver load balancing, failover,
and connection retry parameters are all used as if an initial database connection is being
established.

Load Balancing, Failover, and Connection Retry


To optimize performance, you can implement client load balancing, connection failover,
and connection retry in your Database Service connection properties. To do this, specify
both primary and alternate servers in the connection URL. The following sections explain
these features:

Client Load Balancing on page 168

Connection Failover on page 169

Connection Retry on page 170

166

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Load Balancing, Failover, and Connection Retry

For details on configuring load balancing, failover, and connection retry properties for
each of the JDBC drivers available with Sonic Database Service, see the following
sections:
Table 8. Documentation for JDBC Driver Connection Properties and Alternate Servers

JDBC Driver

Connection Properties Documentation

Progress Open Edge

Progress OpenEdge Database on page 176

Progress OpenEdge Connection Failover Properties on page 181

Specifying Alternate Servers for the Progress OpenEdge Driver on page 182

Progress OpenEdge Driver Data Types on page 184

DB2 Driver Connection Properties on page 185

DB2 Driver Connection Failover Properties on page 198

Specifying Alternate Servers for the DB2 Driver on page 198

DB2 Driver Data Types on page 200

Informix Driver Connection Properties on page 201

Informix Driver Connection Failover Properties on page 209

Specifying Alternate Servers for the Informix Driver on page 209

Informix Driver Data Types on page 210

Oracle Driver Connection Properties on page 212

Oracle Driver Connection Failover Properties on page 223

Specifying Alternate Servers for the Oracle Driver on page 224

Oracle Driver Data Types on page 225

Microsoft SQL Server Driver Connection Properties on page 227

Microsoft SQL Server Driver Connection Failover Properties on page 238

Specifying Alternate Servers for the Microsoft SQL Server Driver on page 238

Microsoft SQL Server Driver Data Types on page 240

Sybase Driver Connection Properties on page 242

Sybase Driver Connection Failover Properties on page 252

Specifying Alternate Servers for the Sybase Driver on page 252

Sybase Driver Data Types on page 254

DB2

Informix

Oracle

Microsoft SQL
Server

Sybase

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

167

Chapter 8: Using the Database Service JDBC Drivers

Client Load Balancing


Client load balancing helps distribute new connections to multiple servers in your
environment so that no one server is overwhelmed with connection requests. When client
load balancing is enabled, the order in which primary and alternate database servers are
tried is random. For example, suppose that client load balancing is enabled as shown in
Figure 1.

Database Server A
(Primary)

Sonic Database Service

Database Server B
(First Alternate)

Database Server C
(Second Alternate)

Figure 1. Client Load Balancing Example

In the example in Figure 1, when client load balancing is enabled the Database Service
first attempts to connect to Database Server B (1). The Database Service then attempts a
connection to Database Server C (2), followed by a connection attempt to Database
Server A (3). In contrast, if client load balancing was not enabled in this scenario, each
database server would be tried in sequential order, primary server first, then each alternate
server based on their entry order in the alternate servers list.
To use client load balancing, specify the following properties in the form property=value
in your connection URL:

LoadBalancing Set this property to true to enable load balancing.

AlternateServers See Specifying Primary and Alternate Servers on page 172.

168

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Load Balancing, Failover, and Connection Retry

Connection Failover
Connection failover allows an application to connect to an alternate, or backup, database
server if the primary database server is unavailable, for example, because of a hardware
failure or traffic overload. Connection failover ensures that the data your critical JDBC
applications depend on is always available.
You can customize the Database Service JDBC drivers for connection failover by
configuring a list of alternate database servers that are tried if the primary server is not
accepting connections. Connection attempts continue until a connection is successfully
established or until all the alternate database servers have been tried the specified number
of times.
For example, suppose you have the environment shown in Figure 2 with multiple database
servers: Database Server A, B, and C. Database Server A is designated as the primary
database server, Database Server B is the first alternate server, and Database Server C is
the second alternate server.

Database Server A
(Primary)

Sonic Database Service

Database Server B
(First Alternate)

Database Server C
(Second Alternate)

Figure 2. Connection Failover Example

In the example shown in Figure 2, the Database Service first attempts to connect to the
primary database server, Database Server A (1). If connection failover is enabled and
Database Server A fails to accept the connection, the Database Service then attempts to
connect to Database Server B (2). If that connection attempt also fails, the Database
Service attempts to connect to Database Server C (3).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

169

Chapter 8: Using the Database Service JDBC Drivers

In this example, it is probable that at least one connection attempt will succeed, but if no
connection attempt succeeds, the driver can retry each database server (primary and
alternates) for a specified number of attempts. The JDBC drivers allow you to customize
the connection retry feature to specify the number of attempts that are made.
A JDBC driver fails over to the next alternate database server only if a successful
connection cannot be established with the current alternate server. If the driver
successfully establishes communication with a database server and the connection request
is rejected by the database server because the login information is invalid, for example,
the driver does not try to connect to the next database server in the list and generates an
exception.
Connection failover provides protection for new connections only and does not preserve
states for transactions or queries.
To use connection failover, see the appropriate section for your database for a list of
property=value pairs to add to your connection URL:

Progress OpenEdge Connection Failover Properties on page 181


DB2 Driver Connection Failover Properties on page 198
Informix Driver Connection Failover Properties on page 209
Oracle Driver Connection Failover Properties on page 223
Microsoft SQL Server Driver Connection Failover Properties on page 238
Sybase Driver Connection Failover Properties on page 252

Connection Retry
Connection retry allows the JDBC driver to retry connections to a list of database servers
(primary and alternate) until a successful connection is established. Use the
ConnectionRetryCount and ConnectionRetryDelay properties to enable and control how
connection retry works.
In the following examples for the different JDBC drivers, if a successful connection is not
established on the drivers first pass through the list of database servers (primary and
alternate), the driver retries the list of servers in the same sequence twice
(ConnectionRetryCount=2). If a successful connection is not established on the first retry
pass through the list of servers, the driver makes another pass through the list of servers.
Because the connection retry delay has been set to five seconds
(ConnectionRetryDelay=5), the driver waits five seconds between retry passes.

170

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Load Balancing, Failover, and Connection Retry

Connection Retry Example for Progress OpenEdge Driver


jdbc:sonic::datadirect:openedge://server1:2003;HostName=TestServer;
DatabaseName=TestServer;User=test;Password=secret;
AlternateServers=(server2:2003;DatabaseName=TEST2,server3:2003;
DatabaseName=TEST3);ConnectionRetryCount=2;ConnectionRetryDelay=5

Connection Retry Example for DB2 Driver


jdbc:sonic:db2://server1:50000;DatabaseName=TEST;
AlternateServers=(server2:50000;DatabaseName=TEST2,
server3:50000;DatabaseName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5

Connection Retry Example for Informix Driver


jdbc:sonic:informix://server1:2003;InformixServer=TestServer;
DatabaseName=TestServer;
AlternateServers=(server2:2003;DatabaseName=TEST2,server3:2003;
DatabaseName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5

Connection Retry Example for Oracle Driver


jdbc:sonic:oracle://server1:1521;ServiceName=TEST;
AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521;ServiceName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5

Connection Retry Example for Microsoft SQL Server Driver


jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST;
AlternateServers=(server2:1433;DatabaseName=TEST2,
server3:1433;DatabaseName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

171

Chapter 8: Using the Database Service JDBC Drivers

Connection Retry Example for Sybase Driver


jdbc:sonic:sybase://server1:4100;DatabaseName=TEST;
AlternateServers=(server2:4100;DatabaseName=TEST2,
server3:4100;DatabaseName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5

Specifying Primary and Alternate Servers


The Sonic Database Service JDBC drivers allow you to specify a list of alternate database
servers that are tried at connection time if the primary server is not accepting connections
using the AlternateServers property. Connection attempts continue until a connection is
successfully established or until all the database servers (primary and alternate) have been
tried the specified number of times.
Connection information for alternate servers is specified using the AlternateServers
property in a connection URL. The value of the AlternateServers property is a string that
has the format:
(servername1[:port1][;property=value[;...]],servername2[:port2]
[;property=value[;...]],...)

where:

is the IP address or server name of the first alternate database server,


the IP address or server name of the second alternate database server,
and so on. The IP address or server name is required for each alternate server entry.
port1 is the port number on which the first alternate database server is listening, port2
is the port number on which the second alternate database server is listening, and so
on. Port numbers are optional for each alternate server entry. If unspecified, the port
number specified for the primary server is used. If a port number is unspecified for
the primary server, the default port number is used (see Table 8 on page 167 to locate
the appendix containing information on the default PortNumber values for the JDBC
drivers).
property=value is an optional connection property, based on the JDBC driver to
which you are connecting.
servername1

servername2 is

172

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Using Activation Daemons

See the following sections for examples that describe how to specify primary and alternate
servers for different JDBC drivers:

Specifying Alternate Servers for the Progress OpenEdge Driver on page 182

Specifying Alternate Servers for the DB2 Driver on page 198

Specifying Alternate Servers for the Informix Driver on page 209

Specifying Alternate Servers for the Oracle Driver on page 224

Specifying Alternate Servers for the Microsoft SQL Server Driver on page 238

Specifying Alternate Servers for the Sybase Driver on page 252

Using Activation Daemons


Using an Activation Daemon is a way to launch new containers as spawned processes of
the container hosting the Activation Daemon. This allows new containers to be launched
by remote administrative clients without the administrator having to log on to that host. A
typical use would be to have the container hosting the Activation Daemon launched as a
Windows service on Windows platforms or a startup process under UNIX.
An Activation Daemon monitors the health of its spawned containers and, depending on
configured rules, restarts those containers upon failure. Normally one Activation Daemon
is deployed per host. Multiple Activation Daemons can be created per domain. Containers
can be launched by the Activation Daemon:

At Activation Daemon startup time

At a configured time

After a container failure (up to a configurable number of retries)

On demand from the Sonic Management Console or via the Activation Daemons
management API
You can create and configure an Activation Daemon to start an ESB Container hosting a
Database Service. The steps required to create, configure, and test the Activation Daemon
are:
1.

Create an Activation Daemon

2.

Add the Activation Daemon to a management container

3.

Add a container to an Activation Daemons activation list

Using Activation Daemons on page 78 provides information about how to complete the
steps to create and configure an Activation Daemon to start an ESB Container hosting a
service.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

173

Chapter 8: Using the Database Service JDBC Drivers

174

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 9

Driver Connection Properties and


Data Types by Database Brand

This chapter contains driver connection properties, connection failover properties, and
driver data types for the following database brands:

Progress OpenEdge Database

DB2

Informix

Oracle

Microsoft SQL Server

Sybase

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

175

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Progress OpenEdge Database


The following sections describe settings for the Sonic Database Services Progress
OpenEdge driver:

Progress OpenEdge Connection Properties

Progress OpenEdge Connection Failover Properties

Specifying Alternate Servers for the Progress OpenEdge Driver

Progress OpenEdge Driver Data Types


See the DataDirect Connect for JDBC Progress OpenEdge Driver Users Guide and
Reference for more information.

Progress OpenEdge Connection Properties


Table 9 describes the JDBC connection properties supported by the Progress OpenEdge
driver. The properties have the format: property=value
Table 9. Connection Properties for the Progress OpenEdge Driver

Property

Description

AlternateServers

A comma-separated list of alternate database servers that the driver will try to
connect to if the primary database server is unavailable. The value of this
property is a string that specifies each alternate server. This string has the
format:

Default: No default
Data type: String

(servername1[:port1][;property=value],servername2[:port2][;property=value],...)

The server name is required for each alternate server entry. Port number and
connection properties (property=value) are optional for each alternate server
entry. If the port is unspecified, the port number of the primary server is used.
The driver only allows one optional property, DatabaseName. For example:
jdbc:datadirect:openedge://server1:4100;
DatabaseName=TEST;User=test;Password=secret
AlternateServers=(server2:4100;DatabaseName=TEST2,
server3:4100;DatabaseName=TEST3)

contains alternate server entries for server2 and server3. The alternate server
entries contain the optional DatabaseName property.

176

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Progress OpenEdge Database


Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connections to the primary database
server, and if specified, alternate servers until a successful connection is
established. Valid values are 0 and any positive integer.

Default: 5
Data type: int

If set to 0, the driver does not try to reconnect after the initial unsuccessful
attempt.
For example, in the case where the following properties are specified:
AlternateServers=(server2:2003,server3:2003,server4:2003)

and
ConnectionRetryCount=1

If a connection is not successfully established on the drivers first pass through


the list of database servers, the driver retries all the servers in the list only once.
If an application sets a login timeout value (for example, using
DataSource.loginTimeout or DriverManager.loginTimeout), the login timeout
takes precedence over this property. For example, if the login timeout expires,
any connection attempts to alternate servers stop.
If the LoadBalancing property is set to true, the driver may sequence through the
list of servers (primary and alternate) in a different order each time.
The ConnectionRetryDelay property specifies the wait interval, in seconds, used
between attempts.
ConnectionRetryDelay
Default: 1
Data type: int

The number of seconds the driver waits before retrying connections to the
primary database server, and if specified, alternate servers when
ConnectionRetryCount is set to a positive integer.
For example, in the case where the following properties are specified:
AlternateServers=(server2:2003,server3:2003,server4:2003)

and
ConnectionRetryCount=2

and
ConnectionRetryDelay=3

If a connection is not successfully established on the drivers first pass through


the list of database servers, the driver retries the list of servers twice. It waits 3
seconds between the first connection retry attempt and the second connection
retry attempt.
If the LoadBalancing property is set to true, the driver may sequence through the
list of servers (primary and alternate) in a different order each time.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

177

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

DatabaseName

The name of the database to which you want to connect.

Default: No default
Data type: String
HostName

The name of the Progress OpenEdge database server to which you want to
connect.

Default: No default
Data type: String

Specifies either the IP address or the server name (if your network supports
named servers) of the primary database server. For example, 122.23.15.12 or
HostName.
This property is supported only for DataSource connections

InsensitiveResultSet
BufferSize
Default: 2048
Data type: int

{-1 | 0 | x}

Determines the amount of memory used by the driver to cache insensitive result
set data. It must have one of the following values:
If set to -1, the driver caches all insensitive result set data in memory. If the size
of the result set exceeds available memory, an OutOfMemoryException is
generated. Because the need to write result set data to disk is eliminated, the
driver processes the data more efficiently.
If set to 0, the driver caches all insensitive result set data in memory, up to a
maximum of 2 GB. If the size of the result set data exceeds available memory,
the driver pages the result set data to disk. Because result set data may be written
to disk, the driver may have to reformat the data to write it correctly to disk.
If set to x, where x is a positive integer, the driver caches all insensitive result set
data in memory, using this value to set the size (in KB) of the memory buffer for
caching insensitive result set data. If the size of the result set data exceeds the
buffer size, the driver pages the result set data to disk. Because the result set data
may be written to disk, the driver may have to reformat the data to write it
correctly to disk. Specifying a buffer size that is a power of 2 results in more
efficient memory use.

178

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Progress OpenEdge Database


Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

LoadBalancing

{true | false}

Default: false

Determines whether the driver will use client load balancing in its attempts to
connect to a list of database servers (primary and alternate). The list of alternate
servers is specified by the AlternateServers property.

Data type: boolean

If set to true, client load balancing is used and the driver attempts to connect to
the list of database servers (primary and alternate servers) in random order.
If set to false (the default), client load balancing is not used and the driver
connects to each server based on their sequential order (primary server first,
then, alternate servers in the order they are specified).
For example, in the case where the following properties are specified:
AlternateServers=(server2:4100,server3:4100,server4:4100)

and
LoadBalancing=true

The driver randomly selects from the list of primary and alternate servers which
server to connect to first. If that connection fails, the driver again randomly
selects from this list of servers until all servers in the list have been tried or a
connection is successfully established.
MaxPooledStatements
Default: 0
Data type: int

The maximum number of pooled prepared statements for this connection.


Setting MaxPooledStatements to an integer greater than zero (0) enables the
Progress OpenEdge drivers internal prepared statement pooling, which is
useful when the driver is not running from within an application server or
another application that provides its own prepared statement pooling.
If set to a positive number, the driver uses that value to cache a certain number
of prepared statements created by an application. For example, if the value of
this property is set to 20, the driver caches the last 20 prepared statements
created by the application. If the value set for this property is greater than the
number of prepared statements used by the application, all prepared statements
created by the application are cached. Because CallableStatement is a sub-class
of PreparedStatement, CallableStatements also are pooled.

Password
REQUIRED
Default: No default
Data type: String

The case-sensitive password used to connect to your OpenEdge database. A


password is required only if security is enabled on your database. If so, contact
your system administrator to obtain your password.
The password is automatically encrypted.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

179

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

PortNumber

The TCP port of the primary database server that is listening for connections to
the Progress OpenEdge database.

REQUIRED
Default: Varies with
operating system

This property is supported only for DataSource connections.

Data type: int


SpyAttributes
Default: No default
Data type: String

Enables DataDirect Spy, a tool that can be used to log detailed information about
calls issued by a running application to any DataDirect Connect for JDBC
driver. The format for the value of this property is:
(spy_attribute[;spy_attribute]...)

where spy_attribute is any valid DataDirect Spy attribute.


For example:
SpyAttributes=(log=(file)/tmp/spy.log;linelimit=80)

logs all JDBC activity to a file using a maximum of 80 characters for each line.
NOTE: If coding a path on Windows to the log file in a Java string, the backslash
character (\) must be preceded by the Java escape character, a backslash. For
example: log=(file)C:\\temp\\spy.log.
DataDirect Spy is not enabled by default.
User
REQUIRED
Default: No default

The case-insensitive user name used to connect to your OpenEdge database. A


user name is required only if security is enabled on your database. If so, contact
your system administrator to get your user name.

Data type: String

180

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Progress OpenEdge Database

Progress OpenEdge Connection Failover Properties


Table 10 summarizes the connection properties that control how connection failover
works with the Database Service Progress OpenEdge driver. See Table 9 for details about
configuring each property.
Table 10. Connection Failover Properties for the Progress Open Edge Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each


server is required. Port number and the DatabaseName connection property are
optional. If the port number is unspecified, the port number specified for the primary
server is used.

ConnectionRetryCount

Number of times the driver retries the primary database server, and if specified,
alternate servers until a successful connection is established. The default is 5.

ConnectionRetryDelay

Wait interval, in seconds, between connection retry attempts when the


ConnectionRetryCount property is set to a positive integer. The default is 1.

DatabaseName

Name of the Progress OpenEdge database server to which you want to connect.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is disabled).

PortNumber

Port listening for connections on the primary database server. This property is
supported only for DataSource connections. The default port number varies,
depending on operating system.

See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

181

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Specifying Alternate Servers for the Progress OpenEdge Driver


The following connection URL for the Progress OpenEdge driver specifies connection
information for the primary and alternate servers:
jdbc:datadirect:openedge://server1:2003;HostName=TestServer;
DatabaseName=TestServer;User=test;Password=secret;
AlternateServers=(server2:2003;HostName=TestServer2,server3:2003)

In this example:
...server1:2003;HostName=TestServer;
DatabaseName=TestServer...

is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property. For example:
...;AlternateServers=(server2:2003;
HostName=TestServer2,server3:2003)

Similarly, connection information for the primary server specified using a JDBC data
source would look something like this:
OpenedgeDataSource mds = new OpenedgeDataSource();
mds.setDescription("My OpenedgeDataSource");
mds.setServerName("server1");
mds.setPortNumber(2003);
mds.setHostName("TestServer");
mds.setDatabaseName("TestServer");
mds.setUser("test");
mds.setPassword("secret");
mds.setAlternateServers=(server2:2003;HostName=
TestServer2,server3:2003)

In this example, connection information for the primary server is specified using the
ServerName, PortNumber, HostName, and DatabaseName properties. Connection
information for alternate servers is specified using the AlternateServers property.

182

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Progress OpenEdge Database

Using the AlternateServers Property


Connection information for alternate servers is specified using the AlternateServers
property with either a connection URL through the JDBC Driver Manager or a JDBC data
source. The value of the AlternateServers property is a string that has the format:
(servername1[:port1][;property=value[;...]],servername2[:port2]
[;property=value[;...]],...)

where:
is the IP address or server name of the first alternate database server,
servername2 is the IP address or server name ofthe second alternate database server, and
so on. The IP address or server name is required for each alternate server entry.
servername1

port1 is

the port number on which the first alternate database server is listening, port2 is
the port number on which the second alternate database server is listening, and so on. The
port number is optional for each alternate server entry. If unspecified, the port number
specified for the primary server is used.

property=value is either of the following connection properties: DatabaseName or


HostName. These connection properties are optional for each alternate server entry.
For example:
jdbc:datadirect:openedge://server1:2003;HostName=TestServer;
DatabaseName=TestServer;User=test;Password=secret;
AlternateServers=(server2:2003;HostName=TestServer2;
DatabaseName=TestServer,server3:2003)

If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL. For example, if
youspecify HostName=TestServer and DatabaseName=TestServer for the primary server,
but do not specify the HostName and DatabaseName properties in the alternate server
entry as shown in the following URL, the driver uses the HostName and DatabaseName
specified for the primary server and tries to connect to the TestServer database on the
Progress OpenEdge server TestServer:
jdbc:datadirect:openedge://server1:2003;HostName=TestServer;
DatabaseName=TestServer;AlternateServers=(server2:2003,server3:2003)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

183

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Progress OpenEdge Driver Data Types


Table 11 lists the data types supported by the Progress OpenEdge driver and describes
how they are mapped to JDBC data types.
Table 11. Progress OpenEdge (OED) Data Types

184

Progress OpenEdge Data Type

JDBC Data Type

bigint

BIGINT

binary

BINARY

bit

BIT

blob

BLOB

char

CHAR

clob

CLOB

date

DATE

decimal

DECIMAL

float

FLOAT

int8

BIGINT

integer

INTEGER

longvarbinary

LONGVARBINARY

longvarchar

LONGVARCHAR

numeric

NUMERIC

real

REAL

smallint

SMALLINT

time

TIME

timestamp

TIMESTAMP

timestamp with time zone

CHAR

tinyint

TINYINT

varbinary

VARBINARY

varchar

VARCHAR

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2

DB2
The following sections describe settings for the Sonic Database Service DB2 driver:

DB2 Driver Connection Properties

DB2 Driver Connection Failover Properties

Specifying Alternate Servers for the DB2 Driver

DB2 Driver Data Types

DB2 Driver Connection Properties


Table 12 describes the JDBC connection properties supported by the DB2 driver. The
properties have the format:
property=value

Note

All connection property names are case-insensitive. For example, Password is the same
as password.

Table 12. DB2 Connection Properties

Property

Description

AddToCreateTable

A string that is appended to the end of all CREATE statements. This property
typically is used to add an in database clause.

OPTIONAL
AlternateID
OPTIONAL

The default schema name that is used to qualify unqualified database


objects in dynamically prepared database queries. Valid values depend on
your DB2 database:

DB2 UDB and DB2 iSeries Sets the value in the DB2 CURRENT
SCHEMA special register. The value of this property must be a valid
DB2 schema name. DB2 UDB and DB2 iSeries do not validate values
specified for the CURRENT SCHEMA register.

DB2 OS/390 Sets the value in the DB2 CURRENT SQLID special
register. The value of this property is validated by the server. Refer to
your IBM documentation for valid values for the CURRENT SQLID
register.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

185

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 12. DB2 Connection Properties (continued)

Property

Description

AlternateServers

A list of alternate database servers that the driver will try to connect to if
the primary database server is unavailable. The value of this property is a
string that specifies each alternate server. This string has the format:

OPTIONAL

(servername1[:port1][;property=value[;...]],
servername2[:port2][;property=value[;...]],...)

The server name is required for each alternate server entry. Port number
and connection properties (property=value) are optional for each
alternate server entry. If the port is unspecified, the port number of the
primary server is used. If the port number of the primary server is
unspecified, the default port number of 50000 is used. Optional connection
properties for the driver are DatabaseName (for DB2 UDB) and
LocationName (for DB2 OS/390 and iSeries). For example:
jdbc:sonic:db2://server1:50000;DatabaseName=TEST;
AlternateServers=(server2:50000;DatabaseName=TEST2,
server3:50000;DatabaseName=TEST3)

contains alternate server entries for server2 and server3. The alternate
server entries contain the optional DatabaseName property.
Other properties are:

ConnectionRetryCount Controls the number of times the driver


retries the list of servers (primary and alternate) while attempting to
establish a connection.
ConnectionRetryDelay Sets the wait interval, in seconds, between

retry attempts.

LoadBalancing

Controls the order in which the driver sequences


through the list of servers (primary and alternate) while attempting to
establish a connection.

See Specifying Primary and Alternate Servers on page 172 for more
information about specifying connection information for primary and
alternate servers.

186

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2
Table 12. DB2 Connection Properties (continued)

Property

Description

BatchPerformanceWorkaround
OPTIONAL

{true | false}

For DB2 UDB 8.1, the native DB2 batch mechanism is used. This
property determines whether certain restrictions are enforced to facilitate
data conversions as follows:

false

The methods used to set the parameter values of a batch


operation performed using a PreparedStatement must match the
database data type of the column the parameter is associated with.
This is because DB2 servers do not perform implicit data conversions.

true This restriction is removed; however, parameter sets may not


be executed in the order they were specified.

The default is false.


CatalogIncludesSynonyms
OPTIONAL

{true | false}

This property value determines behavior as follows:

true

Synonyms are included in the result sets returned from the

DatabaseMetaData.getColumns method.

false

Synonyms are omitted from result sets.

The default is true.


This property is only applicable for DB2 UDB 7.1 and 7.2, DB2 OS/390,
and DB2 iSeries. This property is ignored for DB2 UDB 8.1. The driver
always returns synonyms for the DatabaseMetaData.getColumns method
when connected to DB2 UDB 8.1.
CatalogSchema
OPTIONAL

The DB2 schema to use for catalog functions. The value must be the name
of a valid DB2 schema.
The default is SYSCAT for DB2 UDB, SYSIBM for DB2 OS/390, and
QSYS2 for DB2 iSeries.
To improve performance, views of system catalog tables can be created in
a schema other than the default catalog schema. Setting this property to a
schema that contains views of the catalog tables allows the driver to use
those views. To ensure that catalog methods function correctly, views for
specific catalog tables must exist in the specified schema. The views that
are required depend on your DB2 database.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

187

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 12. DB2 Connection Properties (continued)

Property

Description

CharsetFor65535

The code page to use to convert character data stored as bit data in
character columns (Char, Varchar, Longvarchar, Char for Bit Data,
Varchar for Bit Data, Longvarchar for Bit Data) defined with CCSID
65535. All character data stored as bit data retrieved from the database
using columns defined with CCSID 65535 is converted using the specified
code page. The value must be a string containing the name of a valid code
page supported by your Java Virtual Machine, for example,
CharsetFor65535=CP950. This property has no effect when writing data to
character columns defined with CCSID 65535.

OPTIONAL

CodePageOverride
OPTIONAL

CollectionId
OPTIONAL

A code page to be used to convert Character and Clob data. The specified
code page overrides the default database code page. All Character and
Clob data retrieved from or written to the database is converted using the
specified code page. The value must be a string containing the name of a
valid code page supported by your Java Virtual Machine, for example,
CodePageOverride=CP950.
The name of the collection or library (group of packages) to which DB2
packages are bound.
The default is NULLID.
This property is ignored for DB2 UDB.

188

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2
Table 12. DB2 Connection Properties (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connection attempts to a list of


database servers (primary and alternate) until a successful connection is
established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry connections if a successful connection


is not established on the drivers first pass through the list.
The default is 0.
For example, in the case where the following properties are specified:
AlternateServers=(server2:50000,server3:50000,server4:50000)

and
ConnectionRetryCount=1

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries all the servers in the
list only once.
If an application sets a login timeout value (for example, using
DriverManager.loginTimeout), the login timeout takes precedence over
this property. For example, if the login timeout expires, any connection
attempts stop.
The ConnectionRetryDelay property specifies the wait interval, in
seconds, used between retry attempts.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

189

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 12. DB2 Connection Properties (continued)

Property

Description

ConnectionRetryDelay
OPTIONAL

The number of seconds the driver will wait between connection retry
attempts when ConnectionRetryCount is set to a positive integer.
The default is 3.
For example, in the case where the following properties are specified:
AlternateServers=(server2:50000,server3:50000,server4:50000)

and
ConnectionRetryCount=2

and
ConnectionRetryDelay=3

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries the list of servers
twice. The driver waits 3 seconds between the first connection retry
attempt and the second connection retry attempt.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.
CreateDefaultPackage
OPTIONAL

{true | false}

This property determines behavior as follows:

true The DB2 driver automatically creates any required DB2


packages.

false The driver creates the required DB2 packages automatically

only if they do not already exist.


The default is false.
For DB2 UDB, this property must be used in conjunction with the
ReplacePackage property.

For DB2 OS/390 and DB2 iSeries, DB2 packages are created in the
collection or library specified by the CollectionId property.
DatabaseName

The name of the database to which you want to connect.


This property is supported only for DB2 UDB.

190

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2
Table 12. DB2 Connection Properties (continued)

Property

Description

DiagnosticFilename
OPTIONAL

The path and filename of the file to which you want state information
logged when an exception is generated. If the file does not already exist,
it will be created the first time state information is generated. If this
property is not specified, state information is not logged. When you
contact Technical Support with a problem, you might be asked to generate
a state information log.
Your application should ensure that the driver is granted read/write
permission to the specified file.

DynamicSections
OPTIONAL

The number of statements in the DB2 package that the DB2 driver will
prepare for a single user.
The default is 200.

Grantee
OPTIONAL

The name of the schema to which you want to grant EXECUTE privileges for
DB2 packages. The value must be a valid DB2 schema. This property is
ignored if the GrantExecute property is set to false.
The default is PUBLIC.

GrantExecute

{true | false}

OPTIONAL

Determines which DB2 schema is granted EXECUTE privileges for DB2


packages as follows:

true EXECUTE privileges are granted to the schema specified by the


Grantee property.

false EXECUTE privileges are granted to the schema that created the
DB2 packages.

The default is true.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

191

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 12. DB2 Connection Properties (continued)

Property

Description

InsensitiveResultSetBufferSize
OPTIONAL

{-1 | 0 | x}

Determines the amount of memory used by the driver to cache insensitive


result set data as follows:

-1 The driver caches all insensitive result set data in memory. If the

size of the result set exceeds available memory, an


OutOfMemoryException is generated. Because the need to write result

set data to disk is eliminated, the driver processes the data more
efficiently.

0 The driver caches all insensitive result set data in memory, up to

a maximum of 2 GB. If the size of the result set data exceeds available
memory, the driver pages the result set data to disk. Because result set
data may be written to disk, the driver may have to reformat the data
to write it correctly to disk.

where x is a positive integer The driver caches all insensitive


result set data in memory, using this value to set the size (in KB) of
the memory buffer for caching insensitive result set data. If the size of
the result set data exceeds the buffer size, the driver pages the result
set data to disk. Because the result set data may be written to disk, the
driver may have to reformat the data to write it correctly to disk.
Specifying a buffer size that is a power of 2 results in more efficient
memory use.
x,

The default is 2048 (KB).

192

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2
Table 12. DB2 Connection Properties (continued)

Property

Description

LoadBalancing

{true | false}

OPTIONAL

Determines whether the driver will use client load balancing in its
attempts to connect to a list of database servers (primary and alternate).
The list of alternate servers is specified by the AlternateServers property.
The LoadBalancing property determines behavior as follows:

true Client load balancing is used and the driver attempts to


connect to the list of database servers (primary and alternate servers)
in random order.

false

Client load balancing is not used and the driver connects to


each server based on their sequential order (primary server first, then,
alternate servers in the order they are specified).

The default is false.


For example, in the case where the following properties are specified:
AlternateServers=(server2:50000,server3:50000,server4:50000)

and
LoadBalancing=true

the driver randomly selects from the list of primary and alternate servers
which server to connect to first. If that connection fails, the driver again
randomly selects from this list of servers until all servers in the list have
been tried or a connection is successfully established.
See Client Load Balancing on page 168 for more information about
specifying connection information for primary and alternate servers.
LocationName

The name of the DB2 location that you want to access.


This property is supported only for DB2 OS/390 and iSeries.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

193

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 12. DB2 Connection Properties (continued)

Property

Description

MaxPooledStatements
OPTIONAL

The maximum number of pooled prepared statements for this connection.


MaxPooledStatements property values determine behavior as follows:

An integer greater than zero (0) Enables the DB2 drivers internal
prepared statement pooling, which is useful when the driver is not
running from within an application server or another application that
provides its own prepared statement pooling. The driver uses this
value to cache a certain number of prepared statements created by an
application. For example, if the value of this property is set to 20, the
driver caches the last 20 prepared statements created by the
application.

A value greater than the number of prepared statements used by the


application All prepared statements created by the application are
cached.

Because CallableStatement is a sub-class of PreparedStatement,


are pooled.

CallableStatements also

The default is 0.
PackageOwner
OPTIONAL

The owner to be used for any DB2 packages that are created.

Password

A case-sensitive password used to connect to your DB2 database. A


password is required only if security is enabled on your database. Contact
your system administrator to obtain your password.

PortNumber

The TCP port of the primary database server that is listening for
connections to the DB2 database.

OPTIONAL

The default is NULL.

The default is 50000.


ReplacePackage

{true | false}

OPTIONAL

Specifies whether the current bind process will replace the existing DB2
packages used by the driver. For DB2 UDB, this property must be used in
conjunction with the CreateDefaultPackage property.
The default is false.

194

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2
Table 12. DB2 Connection Properties (continued)

Property

Description

SecurityMechanism

{ClearText | EncryptedPassword | EncryptedUIDPassword}

OPTIONAL

Determines the security method the driver uses to authenticate the user to
the DB2 server when establishing a connection. If the specified
authentication method is not supported by the DB2 server, the connection
fails and the driver generates an exception. This property determines
behavior as follows:

ClearText

The driver sends the password in clear text to the DB2


server for authentication.

EncryptedPassword The driver sends an encrypted password to the

DB2 server for authentication.

EncryptedUIDPassword The driver sends an encrypted user ID and


password to the DB2 server for authentication.

The default is ClearText.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

195

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 12. DB2 Connection Properties (continued)

Property

Description

SendStreamAsBlob

{true | false}

OPTIONAL

Determines whether binary stream data that is less than 32K bytes is sent
to the database as Long Varchar for Bit Data or Blob data. Binary stream
data that is less than 32K bytes can be inserted into a Long Varchar for
Bit Data column, which has a maximum length of 32K bytes, or a Blob
column. Binary streams that are larger than 32K bytes can only be inserted
into a Blob column. The driver always sends binary stream data larger than
32K bytes to the database as Blob data. This property determines behavior
as follows:

true The driver sends binary stream data that is less than 32K to
the database as Blob data. If the target column is a Long Varchar for
Bit Data column and not a Blob column, the Insert or Update
statement fails. The driver automatically retries the Insert or Update
statement, sending the data as Long Varchar for Bit Data, if the
stream passed into the driver is resettable. Sending binary stream data
that is less than 32K bytes in length initially as a Blob significantly
improves performance if the Insert or Update column is a Blob
column.

false

The driver sends binary stream data that is less than 32K to
the database as Long Varchar for Bit Data data. If the target column
is a Blob column and not a Long Varchar for Bit Data column, the
Insert or Update statement fails. The driver retries the Insert or
Update statement, sending the data as Blob data.

The default is false.


ServerName

196

Specifies either the IP address or the server name (if your network
supports named servers) of the primary database server. For example,
122.23.15.12 or DB2Server.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2
Table 12. DB2 Connection Properties (continued)

Property

Description

StripNewlines
OPTIONAL

{true | false}

Specifies whether new-line characters in a database operation are sent to


the DB2 server:

true The DB2 driver removes all new-line characters from


database operations.

If you know that the database operations used in your


application do not contain new-line characters, setting StripNewLines
to false eliminates parsing by the DB2 server and improves
performance.
The default is true.

false

UseCurrentSchema

{true | false}

OPTIONAL

Specifies whether results are restricted to the tables in the current schema
if a DatabaseMetaData.getTables call is called without specifying a
schema or if the schema is specified as the wildcard character %.
Restricting results to the tables in the current schema improves the
performance of calls for getTables methods that do not specify a schema.
This property determines behavior as follows:

true Results that are returned from the getTables method are
restricted to tables in the current schema.

false Results of the getTables method are not restricted.


The default is false.

User

The case-sensitive user name used to connect to the DB2 database.

WithHoldCursors

{true | false}

OPTIONAL

Determines whether the cursor stays open on commiteither DB2 closes


all open cursors (Delete cursors) after a commit or leaves them open
(Preserve cursors):

true

The cursor behavior is Preserve.

false The cursor behavior is Delete. Rolling back a transaction


closes all cursors regardless of how this property is specified.
The default is true.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

197

Chapter 9: Driver Connection Properties and Data Types by Database Brand

DB2 Driver Connection Failover Properties


Table 13 summarizes the connection properties that control how connection failover
works with the Database Service DB2 driver. See Table 12 for details about configuring
each property.
Table 13. Connection Failover Properties for the DB2 Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each


server is required. Port number and supported connection properties (DatabaseName
or LocationName) are optional. If the port number is unspecified, the port specified
for the primary server is used. If a port number is not specified for the primary
server, a default port number of 50000 is used.

ConnectionRetryCount

Number of times the driver retries the list of database servers (primary and alternate)
until a successful connection is established. The default is 0 (connection retry is not
used).

ConnectionRetryDelay

Wait interval, in seconds, used between attempts to connect to a list of database


servers (primary and alternate) when the ConnectionRetryCount property is set to a
positive integer. The default is 3.

DatabaseName

The name of the database to which you want to connect.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is not used).

See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.

Specifying Alternate Servers for the DB2 Driver


The following connection URL for the DB2 driver specifies connection information for
the primary and alternate servers:
jdbc:sonic:db2://server1:50000;DatabaseName=TEST;
AlternateServers=(server2:50000;DatabaseName=TEST2,
server3:50000;DatabaseName=TEST3)

198

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

DB2

In this example:
...server1:50000;DatabaseName=TEST...

is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property, in this
example:
...;AlternateServers=(server2:50000;DatabaseName=TEST2, server3:50000;DatabaseName=TEST3)

You can specify the optional connection properties DatabaseName or LocationName for each
alternate server entry. For example:
dbc:sonic:db2://server1:50000;DatabaseName=TEST;
AlternateServers=(server2:50000;DatabaseName=TEST2,
server3:50000;DatabaseName=TEST2)

or
jdbc:sonic:db2://server1:50000;LocationName=TEST;
AlternateServers=(server2:50000;LocationName=TEST2,
server3:50000;LocationName=TEST3)

If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL for the primary
server. For example, if you specify DatabaseName=TEST for the primary server, but do not
specify a database name in the alternate server entry as shown in the following URL, the
driver uses the database name specified for the primary server and tries to connect to the
TEST database on the alternate server:
jdbc:sonic:db2://server1:50000;DatabaseName=TEST;
AlternateServers=(server2:50000,server3:50000)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

199

Chapter 9: Driver Connection Properties and Data Types by Database Brand

DB2 Driver Data Types


Table 14 lists the data types supported by the DB2 driver and describes how they are
mapped to JDBC data types.
Table 14. DB2 Data Types

DB2 Data Type

JDBC Data Type

Database Comments

Bigint

BIGINT

Supported only for DB2 UDB 8.1.

Blob

BLOB

Supported only for DB2 UDB 8.1, DB2 OS/390,


and DB2 iSeries V5R2.

Char

CHAR

Char for Bit Data

BINARY

Clob

CLOB

Date

DATE

DBClob

CLOB

Decimal

DECIMAL

Double

DOUBLE

Float

FLOAT

Integer

INTEGER

Long Varchar

LONGVARCHAR

Long Varchar for Bit Data

LONGVARBINARY

Numeric

NUMERIC

Real

REAL

Rowid

VARBINARY

Smallint

SMALLINT

Time

TIME

Timestamp

TIMESTAMP

Varchar

VARCHAR

Varchar for Bit Data

VARBINARY

200

Supported only for DB2 UDB 8.1, DB2 7.x OS/390,


and DB2 iSeries V5R2.

Supported only for DB2 OS/390 and DB2 iSeries V5R2.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Informix

Informix
The following sections describe settings for the Sonic Database Service Informix driver:

Informix Driver Connection Properties

Informix Driver Connection Failover Properties

Specifying Alternate Servers for the Informix Driver

Informix Driver Data Types

Informix Driver Connection Properties


Table 15 describes the JDBC connection properties supported by the Informix driver. The
properties have the format:
property=value

Note

All connection property names are case-insensitive. For example, Password is the same
as password.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

201

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Table 15. Informix Connection Properties

Property

Description

AlternateServers

A comma-separated list of alternate database servers the driver will try to


connect to if the primary database server is unavailable. The value of this
property is a string that specifies each alternate server. This string has the
format:

OPTIONAL

(servername1[:port1][;property=value[;...]],
servername2[:port2][;property=value[;...]],...)

The server name is required for each alternate server entry. Port number
and connection properties (property=value) are optional for each
alternate server entry. If the port is unspecified, the port number of the
primary server is used. Optional connection properties for the driver are
DatabaseName and InformixServer. For example, the following URL:
jdbc:sonic:informix://server1:2003;
InformixServer=TestServer;DatabaseName=Test;
AlternateServers=(server2:2003;InformixServer=
TestServer2,server3:2003;InformixServer=TestServer3)

contains alternate server entries for server2 and server3. The alternate
server entries contain the optional InformixServer property.
Other properties are:

ConnectionRetryCount Controls the number of times the driver


retries the list of servers (primary and alternate) while attempting to
establish a connection.
ConnectionRetryDelay Sets the wait interval, in seconds, between

retry attempts.

LoadBalancing

Controls the order in which the driver sequences


through the list of servers (primary and alternate) while attempting to
establish a connection.

See Specifying Primary and Alternate Servers on page 172 for more
information about specifying connection information for primary and
alternate servers.
CodePageOverride
OPTIONAL

202

The code page the driver uses when converting character data. The
specified code page overrides the default database code page. All
character data retrieved from or written to the database is converted using
the specified code page. The value must be a string containing the name
of a valid code page supported by your Java Virtual Machine, for example,
CodePageOverride=CP950.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Informix
Table 15. Informix Connection Properties (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connections to a list of database


servers (primary and alternate) until a successful connection is
established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry a connection to the list of database
servers if a connection is not established on the drivers first pass through
the list.
The default is 0.
For example, in the case where the following properties are specified:
AlternateServers=(server2:2003,server3:2003,server4:2003))

and
ConnectionRetryCount=1

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries all the servers in the
list only once.
If an application sets a login timeout value, the login timeout takes
precedence over this property. For example, if the login timeout expires,
any connection attempts to alternate servers stop.
If the LoadBalancing property is set to true, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
The ConnectionRetryDelay property specifies the wait interval, in
seconds, used between retry attempts.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

203

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 15. Informix Connection Properties (continued)

Property

Description

ConnectionRetryDelay
OPTIONAL

The number of seconds the driver will wait between connection retry
attempts when ConnectionRetryCount is set to a positive integer.
The default is 3.
For example, in the case where the following properties are specified:
AlternateServers=(server2:2003,server3:2003,server4:2003))

and
ConnectionRetryCount=2

and
ConnectionRetryDelay=3

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries the list of servers
twice. It waits 3 seconds between the first connection retry attempt and the
second connection retry attempt.
NOTE: If the LoadBalancing property is set to true, the driver may
sequence through the list of servers (primary and alternate) in a different
order each time.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.
DatabaseName

The name of the database to which you want to connect.


If this property is not specified, a connection is established to the specified
server without connecting to a particular database. A connection that is
established to the server without connecting to the database allows an
application to use CREATE DATABASE and DROP DATABASE database queries.
These statements require that the driver cannot be connected to a database.
An application can connect to the database after the connection is
established by executing the DATABASE database query.
Refer to your IBM Informix documentation for details on using the CREATE
and DATABASE database queries.

DATABASE, DROP DATABASE,

204

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Informix
Table 15. Informix Connection Properties (continued)

Property

Description

DBDate

Sets the Informix DBDate server environment variable for formatting


literal date values when inserting, updating, and retrieving data in DATE
columns. Using this property, you can customize:

OPTIONAL

Order in which the month, day, and year fields appear in a date string

Year field to contain two or four digits

Separator character used to separate the date fields

Valid values are:


DMY2

Y4DM

DMY4

Y4MD

MDY2

Y2DM

MDY4

Y4MD

where D is a 2-digit day field, M is a 2-digit month field, Y2 is a 2-digit year


field, and Y4 is a 4-digit year field.
If unspecified, the format of literal date values conforms to the default
server behavior.
Optionally, a separator character may be specified as the last character of
the value. Valid separator characters are:
Hyphen (-)
Period (.)
Forward slash (/)
If a separator is not specified, a forward slash (/) is used to separate the
fields. For example, a value of Y4MD- specifies a date format that has a 4digit year, followed by the month and then by the day. The date fields are
separated by a hyphen (-). For example: 2004-02-15.
This property does not affect the format of the string in the date escape
syntax. Dates specified using the date escape syntax always use the JDBC
escape format
yyyy-mm-dd.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

205

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 15. Informix Connection Properties (continued)

Property

Description

DiagnosticFilename
OPTIONAL

The path and filename of the file to which you want state information
logged when an exception is generated. If the file does not already exist,
it will be created the first time state information is generated. If this
property is not specified, state information is not logged. When you
contact Technical Support with a problem, you might be asked to generate
a state information log.
Your application should ensure that the driver is granted read/write
permission to the specified file.

InformixServer

The name of the Informix database server to which you want to connect.

InsensitiveResultSetBufferSize

{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive


result set data:

-1 The driver caches all insensitive result set data in memory. If the

size of the result set exceeds available memory, an


OutOfMemoryException is generated. Because the need to write result

set data to disk is eliminated, the driver processes the data more
efficiently.

0 The driver caches all insensitive result set data in memory, up to

a maximum of 2 GB. If the size of the result set data exceeds available
memory, the driver pages the result set data to disk. Because result set
data may be written to disk, the driver may have to reformat the data
to write it correctly to disk.

x, where x is a positive integer The driver caches all insensitive


result set data in memory, using this value to set the size (in KB) of
the memory buffer for caching insensitive result set data. If the size of
the result set data exceeds the buffer size, the driver pages the result
set data to disk. Because the result set data may be written to disk, the
driver may have to reformat the data to write it correctly to disk.
Specifying a buffer size that is a power of 2 results in more efficient
memory use.

The default is 2048 (KB)

206

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Informix
Table 15. Informix Connection Properties (continued)

Property

Description

LoadBalancing

{true | false}

OPTIONAL

Determines whether the driver will use client load balancing in its
attempts to connect to a list of database servers (primary and alternate).
The list of alternate servers is specified by the AlternateServers property.
The LoadBalancing property determines behavior as follows:

true The driver uses client load balancing and attempts to connect
to the database servers (primary and alternate servers) in random
order.

false

Client load balancing is not used and the driver connects to


each server based on their sequential order (primary server first, then,
alternate servers in the order they are specified).

The default is false.


For example, in the case where the following properties are specified:
AlternateServers=(server2:2003,server3:2003;server4:2003)

and
LoadBalancing=true

the driver randomly selects from the list of primary and alternate servers
which server to connect to first. If that connection fails, the driver again
randomly selects from this list of servers until all servers in the list have
been tried or a connection is successfully established.
See Client Load Balancing on page 168 for more information about
specifying connection information for primary and alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

207

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 15. Informix Connection Properties (continued)

Property

Description

MaxPooledStatements

The maximum number of pooled prepared statements for this connection.


MaxPooledStatements property values determine behavior as follows:

OPTIONAL

An integer greater than zero (0) Enables the Informix drivers


internal prepared statement pooling, which is useful when the driver
is not running from within an application server or another
application that provides its own prepared statement pooling. The
driver uses this value to cache a certain number of prepared
statements created by an application. For example, if the value of this
property is set to 20, the driver caches the last 20 prepared statements
created by the application.

A value greater than the number of prepared statements used by the


application All prepared statements created by the application are
cached.

Because CallableStatement is a sub-class of PreparedStatement,


are pooled.

CallableStatements also

The default is 0.
Password

A case-insensitive password used to connect to your Informix database. A


password is required only if security is enabled on your database. If so,
contact your system administrator to obtain your password.

User

The case-insensitive default user name used to connect to the Informix


database. A user name is required only if security is enabled on your
database. If so, contact your system administrator to obtain your user
name.

208

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Informix

Informix Driver Connection Failover Properties


Table 16 summarizes the connection properties that control how connection failover
works with the Database Service DB2 driver. See Table 15 for details about configuring
each property.
Table 16. Connection Failover Properties for the Informix Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each


server is required. Port number and supported connection properties (DatabaseName
or InformixServer) are optional. If the port number is unspecified, the port
specified for the primary server is used. If a port number is not specified for the
primary server, the port specified for the primary server is used.

ConnectionRetryCount

Number of times the driver retries the list of database servers (primary and alternate)
until a successful connection is established. The default is 0 (connection retry is not
used).

ConnectionRetryDelay

Wait interval, in seconds, used between attempts to connect to a list of database


servers (primary and alternate) when the ConnectionRetryCount property is set to a
positive integer. The default is 3.

DatabaseName

The name of the database to which you want to connect.

InformixServer

The name of the Informix database server to which you want to connect.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is disabled).

See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.

Specifying Alternate Servers for the Informix Driver


The following connection URL for the Informix driver specifies connection information
for the primary and alternate servers:
jdbc:sonic:informix://server1:2003;InformixServer=TestServer;
DatabaseName=TestServer;
AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

209

Chapter 9: Driver Connection Properties and Data Types by Database Brand

In this example:
...server1:2003;InformixServer=TestServer;DatabaseName=TestServer...

is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property, in this
example:
...;AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)

You can specify the optional connection properties DatabaseName or InformixServer for
each alternate server entry. For example:
jdbc:sonic:informix://server1:2003;InformixServer=TestServer;
DatabaseName=TestServer;
AlternateServers=(server2:2003;InformixServer=TestServer2;
DatabaseName=TestServer,server3:2003)

If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL for the primary
server. For example, if you specify InformixServer=TestServer and
DatabaseName=TestServer for the primary server, but do not specify the InformixServer
and DatabaseName properties in the alternate server entry as shown in the following URL,
the driver uses the InformixServer and DatabaseName specified for the primary server and
tries to connect to the TestServer database on the Informix server TestServer:
jdbc:sonic:informix://server1:2003;InformixServer=TestServer;
DatabaseName=TestServer;AlternateServers=(server2:2003,server3:2003)

Informix Driver Data Types


Table 17 lists the data types supported by the Informix driver and describes how they are
mapped to JDBC data types.
Table 17. Informix Data Types

210

Informix Data Type

JDBC Data Type

blob

BLOB

boolean

BIT

byte

LONGVARBINARY

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Informix
Table 17. Informix Data Types (continued)

Informix Data Type

JDBC Data Type

clob

CLOB

char

CHAR

date

DATE

datetime hour to second

TIME

datetime year to day

DATE

datetime year to fraction(5)

TIMESTAMP

datetime year to second

TIMESTAMP

decimal

DECIMAL

float

FLOAT

int8

BIGINT

integer

INTEGER

lvarchar

VARCHAR

money

DECIMAL

nchar

CHAR

nvarchar

VARCHAR

serial

INTEGER

serial8

BIGINT

smallfloat

REAL

smallint

SMALLINT

text

LONGVARCHAR

varchar

VARCHAR

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

211

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Oracle
The following sections describe settings for the Sonic Database Service Oracle driver:

Oracle Driver Connection Properties

Oracle Driver Connection Failover Properties

Specifying Alternate Servers for the Oracle Driver

Oracle Driver Data Types

Oracle Driver Connection Properties


Table 18 describes the JDBC connection properties supported by the Oracle driver. The
properties have the format:
property=value

Note

212

All connection property names are case-insensitive. For example, Password is the same
as password.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle
Table 18. Connection Properties for the Oracle Driver

Property

Description

AlternateServers

A comma-separated list of alternate database servers that the driver will


try to connect to if the primary database server is unavailable. The value
of this property is a string that specifies each alternate server. This string
has the format:

OPTIONAL

(servername1[:port1][;property=value[;...]],
servername2[:port2][;property=value[;...]],...)

The server name is required for each alternate server entry. Port number
and connection properties (property=value) are optional for each
alternate server entry. If the port is unspecified, the port number of the
primary server is used. If the port number of the primary server is
unspecified, the default port number of 1521 is used. Optional connection
properties are ServiceName and SID. For example:
jdbc:datadirect:oracle://server1:1521;
ServiceName=TEST;AlternateServers=(server2:1521;
ServiceName=TEST2,server3:1521;ServiceName=TEST3)

contains alternate server entries for server2 and server3. The alternate
server entries contain the optional ServiceName property. Similarly, you
can use the optional SID property instead.
Other properties include:

ConnectionRetryCount Controls the number of times the driver


retries the list of servers (primary and alternate) while attempting to
establish a connection.
ConnectionRetryDelay Sets the wait interval, in seconds, between

retry attempts.

LoadBalancing

Controls the order in which the driver sequences


through the list of servers (primary and alternate) while attempting
to establish a connection.

If using a tnsnames.ora file to retrieve connection information, do not


specify this property.
See Specifying Primary and Alternate Servers on page 172 for more
information about specifying connection information for primary and
alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

213

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

BatchPerformanceWorkaround

{true | false}

OPTIONAL

Determines the method used to execute batch operations:

true The native Oracle batch mechanism is used. The native


Oracle batch mechanism does not return individual update counts for
each statement or parameter set in the batch. For this reason, the
driver returns a value of SUCCESS_NO_INFO (-2) for each entry in the
returned update count array.

false

The JDBC 3.0-compliant batch mechanism is used. If an


application can accept not receiving update count information,
setting this property to true can significantly improve performance.

The default is false.


CatalogIncludesSynonyms
DEPRECATED

This property is recognized for compatibility with existing data sources,


but we recommend that you use the CatalogOptions property instead to
include synonyms in result sets.

CatalogOptions

{0 | 1 | 2 | 3}

OPTIONAL

Determines the type of information included in result sets returned from


catalog functions:

Result sets contain default DatabaseMetaData results.

Result sets contain Remarks information returned from the

DatabaseMetaData methods: getTables and getColumns.

Result sets contain synonyms returned from the

DatabaseMetaData methods: getColumns, getProcedures,


getProcedureColumns,

and getIndexInfo.

3 Result sets contain remarks and synonyms (as described in


options 1 and 2).

The default is 2.

214

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle
Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connections to a list of database


servers (primary and alternate) until a successful connection is
established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry a connection to the list of database
servers if a connection is not established on the drivers first pass through
the list.
The default is 0.
For example, in the case where the following properties are specified:
AlternateServers=(server2:1521,server3:1521,server4:1521)

and
ConnectionRetryCount=1

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries all the servers in the
list only once.
If an application sets a login timeout value (for example, using
DriverManager.loginTimeout), the login timeout takes precedence over
this property. For example, if the login timeout expires, any connection
attempts to alternate servers stop.
If the LoadBalancing property also is specified, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
The ConnectionRetryDelay property specifies the wait interval, in
seconds, used between attempts.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

215

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

ConnectionRetryDelay

The number of seconds the driver waits before retrying connections to a


list of database servers (primary and alternate) when
ConnectionRetryCount is set to a positive integer.

OPTIONAL

The default is 3.
For example, in the case where the following properties are specified:
AlternateServers=(server2:1521,server3:1521,server4:1521)

and
ConnectionRetryCount=2

and
ConnectionRetryDelay=3

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries the list of servers
twice. The driver waits 3 seconds between the first connection retry
attempt and the second connection retry attempt.
If the LoadBalancing property also is specified, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
The ConnectionRetryCount property specifies the number of times the
driver will attempt to connect to all the servers in the list of alternate
servers.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.
DiagnosticFilename
OPTIONAL

The path and filename of the file to which you want state information
logged when an exception is generated. If the file does not already exist,
it will be created the first time state information is generated. If this
property is not specified, state information is not logged. When you
contact Technical Support with a problem, you might be asked to
generate a state information log.
Your application should ensure that the driver is granted read/write
permission to the specified file.

216

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle
Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

FetchTSWTZasTimestamp

{true | false}

OPTIONAL

This property determines behavior as follows:

true

Allows column values with the TIMESTAMP WITH TIME ZONE


data type (Oracle9i or higher) to be retrieved as a JDBC TIMESTAMP
data type.

false Column values with the TIMESTAMP


type must be retrieved as a string.

WITH TIME ZONE data

The default is false.


InsensitiveResultSetBufferSize

{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive


result set data:

The driver caches all insensitive result set data in memory. If


the size of the result set exceeds available memory, an
OutOfMemoryException is generated. Because the need to write result
set data to disk is eliminated, the driver processes the data more
efficiently.

0 The driver caches all insensitive result set data in memory, up to

-1

a maximum of 2 GB. If the size of the result set data exceeds


available memory, the driver pages the result set data to disk.
Because result set data may be written to disk, the driver may have
to reformat the data to write it correctly to disk.

x, where x is a positive integer The driver caches all insensitive


result set data in memory, using this value to set the size (in KB) of
the memory buffer for caching insensitive result set data. If the size
of the result set data exceeds the buffer size, the driver pages the
result set data to disk. Because the result set data may be written to
disk, the driver may have to reformat the data to write it correctly to
disk. Specifying a buffer size that is a power of 2 results in more
efficient memory use.

The default is 2048 (KB).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

217

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

LoadBalancing

{true | false}

OPTIONAL

Determines whether the driver will use client load balancing in its
attempts to connect to a list of database servers (primary and alternate).
The list of alternate servers is specified by the AlternateServers
property. The LoadBalancing property determines behavior as follows:

true Client load balancing is used and the driver attempts to


connect to the list of database servers (primary and alternate servers)
in random order.

false Client load balancing is not used and the driver connects to

each server based on their sequential order (primary server first,


then, alternate servers in the order they are specified).
The default is false.
For example, in the case where the following properties are specified:
AlternateServers=(server2:1521,server3:1521,server4:1521)

and
LoadBalancing=true

the driver randomly selects from the list of primary and alternate servers
which server to connect to first. If that connection fails, the driver again
randomly selects from this list of servers until all servers in the list have
been tried or a connection is successfully established.
If using a tnsnames.ora file to retrieve connection information, do not
specify this property.
See Client Load Balancing on page 168 or more information about
specifying connection information for primary and alternate servers.

218

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle
Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

MaxPooledStatements

The maximum number of pooled prepared statements for this connection.


MaxPooledStatements property values determine behavior as follows:

OPTIONAL

An integer greater than zero (0) Enables the Oracle drivers


internal prepared statement pooling, which is useful when the driver
is not running from within an application server or another
application that provides its own prepared statement pooling. The
driver uses this value to cache a certain number of prepared
statements created by an application. For example, if the value of this
property is set to 20, the driver caches the last 20 prepared statements
created by the application.

A value greater than the number of prepared statements used by the


application All prepared statements created by the application are
cached.

Because CallableStatement is a sub-class of PreparedStatement,


are pooled.

CallableStatements also

The default is 0.
Password

A case-insensitive password used to connect to your Oracle database. A


password is required only if security is enabled on your database. If so,
contact your system administrator to obtain your password.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

219

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

ServerType

{Shared | Dedicated}

OPTIONAL

Specifies whether the connection is established using a shared or


dedicated server process (UNIX) or thread (Windows):

Shared The server process to be used is retrieved from a pool. The

socket connection between the client and server is made to a


dispatcher process on the server. This setting allows there to be fewer
processes than the number of connections, reducing the need for
server resources. Use this value when a server must handle many
users with fewer server resources.

Dedicated

A server process is created to service only that


connection. When that connection ends, so does the process (UNIX)
or thread (Windows). The socket connection is made directly
between the application and the dedicated server process or thread.
When connecting to UNIX servers, a dedicated server process can
provide significant performance improvement, but uses more
resources on the server. When connecting to Windows servers, the
server resource penalty is insignificant. Use this value if you have a
batch environment with low numbers of users.

Unspecified The driver uses the server type set on the server.

If using a tnsnames.ora file to provide connection information, do not


specify this property.
ServiceName
OPTIONAL

The database service name that specifies the database used for the
connection. The service name is a string that is the global database
namea name that typically comprises the database name and domain
name. For example:
sales.us.acme.com

This property is useful to specify connections to an Oracle Real


Application Clusters (RAC) system rather than a specific Oracle instance
because the nodes in a RAC system share a common service name.
If using a tnsnames.ora file to provide connection information, do not
specify this property.

220

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle
Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

SID

The Oracle System Identifier that refers to the instance of the Oracle
database running on the server. This property is mutually exclusive with
the ServiceName property.

OPTIONAL

The default is ORCL, which is the default SID that is configured when
installing your Oracle database.
If using a tnsnames.ora file to provide connection information, do not
specify this property.
TNSNamesFile
OPTIONAL

The path and filename to the tnsnames.ora file from which connection
information is retrieved. The tnsnames.ora file contains connection
information that is mapped to Oracle net service names. Using a
tnsnames.ora file to centralize connection information simplifies
maintenance when changes occur.
The value of this property must be a valid path and filename to a
tnsnames.ora file.
If you specify this property, you also must specify the TNSServerName
property.
If this property is specified, do not specify the following properties to
prevent connection information conflicts:

AlternateServers

LoadBalancing

PortNumber

ServerName

ServerType

ServiceName

SID

If any of these properties are specified in addition to this property, the


driver generates an exception.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

221

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

TNSServerName

The Oracle net service name used to reference the connection


information in a tnsnames.ora file. The value of this property must be a
valid net service name entry in the tnsnames.ora file specified by the
TNSNamesFile property.

OPTIONAL

If this property is specified, you also must specify the TNSNamesFile


property.
If this property is specified, do not specify the following properties to
prevent connection information conflicts:

AlternateServers

LoadBalancing

PortNumber

ServerName

ServerType

ServiceName

SID

If any of these properties are specified in addition to this property, the


driver generates an exception.
User

222

The case-insensitive default user name used to connect to your Oracle


database. A user name is required only if security is enabled on your
database. If so, contact your system administrator to obtain your user
name. Operating System authentication is not currently supported by the
Oracle driver.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle

Oracle Driver Connection Failover Properties


Table 19 summarizes the connection properties that control how connection failover
works with the Oracle driver. See Table 18 for details about configuring each property.
Table 19. Connection Failover Properties for the Oracle Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each


server is required. Port number and the ServiceName or SID connection properties
are optional. If the port number is unspecified, the port specified for the primary
server is used. If a port number is not specified for the primary server, the default
port number of 1521 is used.

ConnectionRetryCount

Number of times the driver retries the list of database servers (primary and alternate)
until a successful connection is established. The default is 0 (connection retry is not
used).

ConnectionRetryDelay

Wait interval, in seconds, used between attempts to connect to a list of database


servers (primary and alternate) when the ConnectionRetryCount property is set to a
positive integer. The default is 3.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is disabled).

ServiceName

The database service name that specifies the database used for the connection. This
property is mutually exclusive with the SID property.

SID

The Oracle System Identifier that refers to the instance of the Oracle database
running on the server. The default is ORCL. This property is mutually exclusive with
the ServiceName property.

See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

223

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Specifying Alternate Servers for the Oracle Driver


The following connection URL for the Oracle driver specifies connection information for
the primary and alternate servers:
jdbc:sonic:oracle://server1:1521;ServiceName=TEST;
AlternateServers=(server2:1521;ServiceName=TEST2,server3:1521;
ServiceName=TEST3)

In this example:
...server1:1521;ServiceName=TEST...

is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property, in this
example:
...;AlternateServers=(server2:1521;ServiceName=TEST2,
server3:50000;ServiceName=TEST3)

You can specify the optional connection properties ServiceName or SID for each alternate
server entry. These properties are mutually exclusive. For example:
jdbc:sonic:oracle://server1:1521;ServiceName=TEST;
AlternateServers=(server2:1521;ServiceName=TEST2,server3:1521)

or
jdbc:sonic:oracle://server1:1521;SID=ORCL;
AlternateServers=(server2:1521;SID=ORCL2,server3:1521)

If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL for the primary
server. For example, if you specify SID=ORCL for the primary server, but do not specify a
SID in the alternate server entry as shown in the following URL, the driver uses the SID
specified for the primary server and tries to connect to the ORCL database on the alternate
server:
jdbc:sonic:oracle://server1:1521;SID=ORCL;
AlternateServers=(server2:1521,server3:1521)

224

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Oracle

Oracle Driver Data Types


The following sections list data types supported by the Oracle driver, and describe the
XMLType data type supported by Oracle9i and higher drivers.

Oracle Data Types


Table 20 lists the data types supported by the Oracle driver and describes how they are
mapped to JDBC data types.
Table 20. Oracle Data Types

Oracle Database

Oracle Data Type

JDBC Data Type

Oracle8i and higher

BFILE

BLOB

BLOB

BLOB

CHAR

CHAR

CLOB

CLOB

DATE

TIMESTAMP

FLOAT(n)

DOUBLE

LONG

LONGVARCHAR

long raw

LONGVARBINARY

NCHAR

CHAR

NCLOB

CLOB

NUMBER (p, s)

DECIMAL

NUMBER

DOUBLE

NVARCHAR2

VARCHAR

TIMESTAMP

TIMESTAMP

TIMESTAMP WITH LOCAL TIME


ZONE

TIMESTAMP

TIMESTAMP WITH TIME ZONE

VARCHAR

VARCHAR2

VARCHAR

XMLType

CLOB

Oracle9i and higher

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

225

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 20. Oracle Data Types (continued)

Oracle Database

Oracle Data Type

JDBC Data Type

Oracle10g only

BINARY_FLOAT

REAL

BINARY_DOUBLE

DOUBLE

XMLType Data Type


The Oracle driver supports tables containing columns specified as XMLType for Oracle9i
and higher. The driver maps the Oracle XMLType data type to the JDBC CLOB data type.
XMLType columns can be used in queries just like any other column type. The data from
XMLType columns can be retrieved as a String, Clob, CharacterStream, or AsciiStream.
When inserting or updating XMLType columns, the data to be inserted or updated must be
in the form of an XMLType data type.
Oracle provides the xmltype() function to construct an XMLType data object. The xmlData
argument of the xmltype() function can be specified as a string literal or a parameter
marker. If a parameter marker is used, the parameter value may be set using the setString,
setClob, setCharacterStream, or setAsciiStream methods.
The following code inserts data into an XMLType column using a statement with a string
literal as the xmlData argument of the xmltype() function:
// Insert xml data as a literal
String sql = "insert into XMLTypeTbl values (1, xmltype('" +
"<emp><empNo>123</empNo><empName>Mark</empName></emp>'))";
Statement stmt = con.createStatement();
stmt.executeUpdate(sql);

The following code inserts data into an XMLType column using a prepared statement:
//

Insert xml data as a String parameter

String xmlStr = "<emp><empNo>234</empNo><empName>Trish</empName></emp>";


String sql = "insert into XMLTypeTbl values (?, xmltype(?))";
PreparedStatement prepStmt = con.prepareStatement(sql);
prepStmt.setInt(1, 2);
prepStmt.setString(2, xmlStr);
prepStmt.executeUpdate();

226

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server

When the data from an XMLType column is retrieved as a Clob, the XMLType data cannot be
updated using the Clob object. Calling the setString, setCharacterStream, or
setAsciiStream methods of a Clob object returned from an XMLType column generates an
SQLException.

Microsoft SQL Server


The following sections describe settings for the Sonic Database Service Microsoft SQL
Server driver:

Microsoft SQL Server Driver Connection Properties

Microsoft SQL Server Driver Connection Failover Properties

Specifying Alternate Servers for the Microsoft SQL Server Driver

Microsoft SQL Server Driver Data Types

Microsoft SQL Server Driver Connection Properties


Table 21 describes the JDBC connection properties supported by the Microsoft SQL
Server driver. The properties have the format:
property=value

Note

All connection property names are case-insensitive. For example, Password is the same
as password.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

227

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 21. Connection Properties for the Microsoft SQL Server Driver

Property

Description

AlternateServers

A comma-separated list of alternate database servers that the driver will


try to connect to if the primary database server is unavailable. The value
of this property is a string that specifies each alternate server. This string
has the format:

OPTIONAL

(servername1[:port1][;property=value],
servername2[:port2][;property=value],...)

The server name is required for each alternate server entry. Port number
and connection properties (property=value) are optional for each
alternate server entry. If the port is unspecified, the port number specified
for the primary server is used. If a port number for the primary server is
unspecified, the default port number of 1433 is used. The driver allows
only one optional connection property, DatabaseName. For example:
jdbc:sonic:sqlserver://server1:1433;
DatabaseName=TEST;AlternateServers=(server2:1433;
DatabaseName=TEST2,server3:1433;DatabaseName=TEST3)

contains alternate server entries for server2 and server3. The alternate
server entries contain the optional DatabaseName property.
Other properties are:

Controls the number of times the driver


retries the list of servers (primary and alternate) while attempting to
establish a connection.

ConnectionRetryCount

ConnectionRetryDelay Sets the wait interval, in seconds, between

retry attempts.

LoadBalancing

Controls the order in which the driver sequences


through the list of servers (primary and alternate) while attempting
to establish a connection.

See Specifying Primary and Alternate Servers on page 172 or more


information about specifying connection information for primary and
alternate servers.

228

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

AlwaysReportTriggerResults

{true | false}

OPTIONAL

Determines how the driver reports results generated by database triggers


(procedures that are stored in the database and executed, or fired, when a
table is modified):

true The driver returns all results, including results generated by


triggers. Multiple trigger results are returned one at a time. Use the
Statement.getMoreResults method to retrieve individual trigger
results. Warnings and errors are reported in the results as they are
encountered.

false The driver does not report trigger results if the statement is

a single Insert, Update, or Delete statement. In this case, the only


result that is returned is the update count generated by the statement
that was executed (if errors do not occur). Although trigger results
are ignored, any errors generated by the trigger are reported. Any
warnings generated by the trigger are enqueued. If errors are
reported, the update count is not reported.
The default is false.
CodePageOverride
OPTIONAL

Specifies the code page the driver uses when converting character data.
The specified code page overrides the default database code page. All
character data retrieved from or written to the database is converted using
the specified code page. The value must be a string containing the name
of a valid code page supported by your Java Virtual Machine, for
example, CodePageOverride=CP950.
If a value is set for the CodePageOverride property and the
SendStringParametersAsUnicode property is set to true, the driver
ignores the SendStringParametersAsUnicode property and generates a
warning. The driver always sends parameters using the code page
specified by CodePageOverride if this property is specified.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

229

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connections to a list of database


servers (primary and alternate) until a successful connection is
established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry a connection to the list of database
servers if a connection is not established on the drivers first pass through
the list.
The default is 0.
For example, in the case where the following properties are specified:
AlternateServers=(server2:1433,server3:1433,server4:1433)

and
ConnectionRetryCount=1

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries all the servers in the
list only once.
If an application sets a login timeout value, the login timeout takes
precedence over this property. For example, if the login timeout expires,
any connection attempts to alternate servers stop.
If the LoadBalancing property is set to true, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
The ConnectionRetryDelay property specifies the wait interval, in
seconds, used between attempts.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.

230

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

ConnectionRetryDelay

The number of seconds the driver waits before retrying a list of database
servers (primary and alternate) when ConnectionRetryCount is set to a
positive integer.

OPTIONAL

The default is 3.
For example, in the case where the following properties are specified:
AlternateServers=(server2:1433,server3:1433,server4:1433)

and
ConnectionRetryCount=2

and
ConnectionRetryDelay=3

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries the list of servers
twice. It waits 3 seconds between the first connection retry attempt and
the second connection retry attempt.
NOTE: If the LoadBalancing property is set to true, the driver may
sequence through the list of servers (primary and alternate) in a different
order each time.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.
DatabaseName

The name of the database to which you want to connect.

OPTIONAL
DiagnosticFilename
OPTIONAL

The path and filename of the file to which you want state information
logged when an exception is generated. If the file does not already exist,
it will be created the first time state information is generated. If this
property is not specified, state information is not logged. When you
contact Technical Support with a problem, you might be asked to
generate a state information log.
Your application should ensure that the driver is granted read/write
permission to the specified file.

HostProcess
OPTIONAL

The process ID of the application connecting to Microsoft SQL Server.


The value of this property appears in the hostprocess column of the
master.dbo.sysprocesses table and may be useful for database
administration purposes.
The default is 0.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

231

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

InsensitiveResultSetBufferSize

{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive


result set data. This property must have one of the following values:

The driver caches all insensitive result set data in memory. If


the size of the result set exceeds available memory, an
OutOfMemoryException is generated. Because the need to write result
set data to disk is eliminated, the driver processes the data more
efficiently.

0 The driver caches all insensitive result set data in memory, up to

-1

a maximum of 2 GB. If the size of the result set data exceeds


available memory, the driver pages the result set data to disk.
Because result set data may be written to disk, the driver may have
to reformat the data to write it correctly to disk.

x, where x is a positive integer The driver caches all insensitive


result set data in memory, using this value to set the size (in KB) of
the memory buffer for caching insensitive result set data. If the size
of the result set data exceeds the buffer size, the driver pages the
result set data to disk. Because the result set data may be written to
disk, the driver may have to reformat the data to write it correctly to
disk. Specifying a buffer size that is a power of 2 results in more
efficient memory use.

The default is 2048 (KB).

232

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

LoadBalancing

{true | false}

OPTIONAL

Determines whether the driver will use client load balancing in its
attempts to connect to a list of database servers (primary and alternate).
The list of alternate servers is specified by the AlternateServers
property. The LoadBalancing property determines behavior as follows:

true Client load balancing is used and the driver attempts to


connect to the list of database servers (primary and alternate servers)
in random order.

false Client load balancing is not used and the driver connects to

each server based on their sequential order (primary server first,


then, alternate servers in the order they are specified).
The default is false.
For example, in the case where the following properties are specified:
AlternateServers=(server2:1433,server3:1433,server4:1433)

and
LoadBalancing=true

the driver randomly selects from the list of primary and alternate servers
which server to connect to first. If that connection fails, the driver again
randomly selects from this list of servers until all servers in the list have
been tried or a connection is successfully established.
See Client Load Balancing on page 168 for more information about
specifying connection information for primary and alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

233

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

MaxPooledStatements

The maximum number of pooled prepared statements for this connection.


MaxPooledStatements property values determine behavior as follows:

OPTIONAL

An integer greater than zero (0) Enables the SQL Server drivers
internal prepared statement pooling, which is useful when the driver
is not running from within an application server or another
application that provides its own prepared statement pooling. The
driver uses this value to cache a certain number of prepared
statements created by an application. For example, if the value of this
property is set to 20, the driver caches the last 20 prepared statements
created by the application.

A value greater than the number of prepared statements used by the


application All prepared statements created by the application are
cached.

Because CallableStatement is a sub-class of PreparedStatement,


are pooled.

CallableStatements also

The default is 0.
NetAddress
OPTIONAL

The Media Access Control (MAC) address of the network interface card
of the application connecting to Microsoft SQL Server. The value of this
property appears in the net_address column of the
master.dbo.sysprocesses table and is used for database administration
purposes.
The default is 000000000000.

Password
OPTIONAL

A case-insensitive password used to connect to your Microsoft SQL


Server database. If a user name is not specified, the driver will use
Windows authentication when connecting to Microsoft SQL Server. In
this case, a password is not required. If a password is required, contact
your system administrator to obtain your password.
Refer to the Progress Sonic ESB Product Family: Installation and
Upgrade Guide for product requirements and configuration that must be
met to use Windows authentication with the SQL Server driver.

ProgramName
OPTIONAL

The name of the application connecting to Microsoft SQL Server. The


value of this property appears in the program_name column of the
master.dbo.sysprocesses table and is useful for database administration
purposes.
The default is an empty string.

234

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

SelectMethod

{direct | cursor}

OPTIONAL

A hint to the driver that determines whether the driver requests a database
cursor for Select statements. Performance and behavior of the driver are
affected by this property, which is defined as a hint because the driver
might not always be able to satisfy the requested method.

Direct

When the driver uses the Direct method, the database


server sends the complete result set in a single response to the driver
when responding to a query. A server-side database cursor is not
created. Typically, responses are not cached by the driver. Using this
method, the driver must process all the response to a query before
another query is submitted. If another query is submitted (using a
different statement on the same connection, for example), the driver
caches the response to the first query before submitting the second
query. Typically, the Direct method performs better than the Cursor
method.

Cursor

When the driver uses the Cursor method, a server-side


cursor is requested. The rows are retrieved from the server in blocks
when returning forward-only result sets. The JDBC Statement
method setFetchSize can be used to control the number of rows that
are retrieved for each request. Performance tests show that the value
of setFetchSize significantly impacts performance when the Cursor
method is used. There is no simple rule for determining the
setFetchSize value that you should use. We recommend that you
experiment with different setFetchSize values to determine which
value gives the best performance for your application. The Cursor
method is useful for queries that produce a large amount of data,
particularly if multiple open result sets are used.

The default is Direct.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

235

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

SendStringParametersAsUnicode

{true | false}

OPTIONAL

Determines whether string parameters are sent to the Microsoft SQL


Server database in Unicode or in the default character encoding of the
database:

true String parameters are sent to Microsoft SQL Server in


Unicode.

false

String parameters are sent in the default encoding, which


can improve performance because the server does not need to
convert Unicode characters to the default encoding. You should,
however, use default encoding only if the parameter string data you
specify is the same as the default encoding of the database.

The default is true.


If a value is specified for the CodePageOverride property and this
property is set to true, this property is ignored and a warning is
generated.
User

The case-insensitive user name used to connect to your Microsoft SQL


Server database. If a user name is not specified, the driver uses Windows
authentication when connecting to the database server. In this case, a user
name is not required. If a user name is required, contact your system
administrator to obtain your user name.

OPTIONAL

Refer to the Progress Sonic ESB Product Family: Installation and


Upgrade Guide for product and configuration requirements that must be
met to use Windows authentication with the SQL Server driver.
UseServerSideUpdatableCursors

{true | false}

Determines whether the driver uses server-side cursors when an


updatable result set is requested:

true Server-side updatable cursors are created when an updatable


result set is requested.

false

The default updatable result set functionality is used.

The default is false.

236

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

WSID

The workstation ID, which typically is the network name of the computer
on which the application resides. If specified, this value is stored in the
hostname column of the master.dbo.sysprocesses table and can be
returned by sp_who and the Transact-SQL HOST_NAME function. The value
is useful for database administration purposes.

OPTIONAL

The default is an empty string.


XATransactionGroup
OPTIONAL

The transaction group ID that identifies any transactions initiated by the


connection. This ID can be used for distributed transaction cleanup
purposes.
You can use the XAResource.recover method to roll back any
transactions left in an unprepared state. When you call
XAResource.recover, any transactions that match the ID on the
connection used to call XAResource.recover are rolled back. For
example, if you specify XATransactionGroup=ACCT200 and call
XAResource.recover on the same connection, any transactions left in an
unprepared state identified by the transaction group ID of ACCT200 are
rolled back.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

237

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Microsoft SQL Server Driver Connection Failover Properties


Table 22 summarizes the connection properties that control how connection failover
works with the Database Service SQL Server driver. See Table 21 for details about
configuring each property.
Table 22. Connection Failover Properties for the Microsoft SQL Server Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each


server is required. Port number and supported connection properties (DatabaseName)
are optional. If the port number is unspecified, the port number specified for the
primary server is used. If a port number is unspecified for the primary server, the
default port number of 1433 is used.

ConnectionRetryCount

Number of times the driver retries the list of database servers (primary and alternate)
until a successful connection is established. The default is 0 (connection retry is not
used).

ConnectionRetryDelay

Wait interval, in seconds, used between attempts to connect to a list of database


servers (primary and alternate) when the ConnectionRetryCount property is set to a
positive integer. The default is 3.

DatabaseName

The name of the database to which you want to connect.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is disabled).

See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.

Specifying Alternate Servers for the Microsoft SQL Server Driver


The following connection URL for the Microsoft SQL Server driver specifies connection
information for the primary and alternate servers:
jjdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST;
AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433;
DatabaseName=TEST3)

In this example:
238

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


....server1:1433;DatabaseName=TEST...

is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property, in this
example:
...;AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433;
DatabaseName=TEST3)

You can specify an optional instance property for each alternate server entry. For
example:
jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST;
AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433;
DatabaseName=TEST3)

or, if connecting to named instances:


jdbc:sonic:sqlserver://server1\\instance1:1433;DatabaseName=TEST;
AlternateServers=(server2\\instance2:1433;DatabaseName=TEST2,s
erver3\\instance3:1433;DatabaseName=TEST3)

If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL for the primary
server. For example, if you specify DatabaseName=TestServer for the primary server, but
do not specify the InformixServer and DatabaseName properties in the alternate server
entry as shown in the following URL, the driver uses the InformixServer and
DatabaseName specified for the primary server and tries to connect to the TEST database on
the alternate server:
jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST;
AlternateServers=(server2:1433,server3:1433)

The SQL Server driver also allows you to specify connections to named instances,
multiple instances of a Microsoft SQL Server database running concurrently on the same
server. If specifying named instances for the primary and alternate servers, the connection
URL would look like this:
jdbc:datadirect:sqlserver://server1\\instance1;
AlternateServers=(server2\\instance2:1433;DatabaseName=TEST2,
server3\\instance3:1433;DatabaseName=TEST3)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

239

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Microsoft SQL Server Driver Data Types


Table 23 lists the data types supported by the Microsoft SQL Server driver and describes
how they are mapped to JDBC data types. These data types are for SQL Server 7 and 2000
unless otherwise noted in the table.
Table 23. Microsoft SQL Server Driver Data Types

240

Microsoft SQL Server


DataBase

Microsoft SQL Server


Data Type

JDBC Data Type

SQL Server 7 and 2000

binary

BINARY

bit

BIT

char

CHAR

datetime

TIMESTAMP

decimal

DECIMAL

decimal() identity

DECIMAL

float

FLOAT

image

LONGVARBINARY

int

INTEGER

int identity

INTEGER

money

DECIMAL

nchar

CHAR

ntext

LONGVARCHAR

numeric

NUMERIC

numeric() identity

NUMERIC

nvarchar

VARCHAR

real

REAL

smalldatetime

TIMESTAMP

smallint

SMALLINT

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Microsoft SQL Server


Table 23. Microsoft SQL Server Driver Data Types (continued)

Microsoft SQL Server


DataBase

Microsoft SQL Server


Data Type

JDBC Data Type

SQL Server 7 and 2000

smallint identity

SMALLINT

smallmoney

DECIMAL

sysname

VARCHAR

text

LONGVARCHAR

timestamp

BINARY

tinyint

TINYINT

tinyint identity

TINYINT

uniqueidentifier

CHAR

varbinary

VARBINARY

varchar

VARCHAR

bigint

BIGINT

bigint identity

BIGINT

sql_variant

VARCHAR

SQL Server 2000 only

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

241

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Sybase
The following sections describe settings for the Sonic Database Service Sybase driver:

Sybase Driver Connection Properties

Sybase Driver Connection Failover Properties

Specifying Alternate Servers for the Sybase Driver

Sybase Driver Data Types

Sybase Driver Connection Properties


Table 24 describes the JDBC connection properties supported by the Sybase driver. The
properties have the format:
property=value

Note

242

All connection property names are case-insensitive. For example, Password is the same
as password.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase
Table 24. Connection Properties for the Sybase Driver

Property

Description

AlternateServers

A comma-separated list of alternate database servers that the driver will


try to connect to if the primary database server is unavailable. The value
of this property is a string that specifies each alternate server. This string
has the format:

OPTIONAL

(servername1[:port1][;property=value],
servername2[:port2][;property=value],...)

The server name is required for each alternate server entry. Port number
and connection properties (property=value) are optional for each
alternate server entry. If the port is unspecified, the port number of the
primary server is used. The driver only allows one optional connection
property, DatabaseName. For example:
jdbc:sonic:sybase://server1:4100;
DatabaseName=TEST;AlternateServers=(server2:4100;
DatabaseName=TEST2,server3:4100;DatabaseName=TEST3)

contains alternate server entries for server2 and server3. The alternate
server entries contain the optional DatabaseName property.
Other properties are:

ConnectionRetryCount Controls the number of times the driver


retries the list of servers (primary and alternate) while attempting to
establish a connection.
ConnectionRetryDelay Sets the wait interval, in seconds, between

retry attempts.

LoadBalancing

Controls the order in which the driver sequences


through the list of servers (primary and alternate) while attempting
to establish a connection.

See Specifying Primary and Alternate Servers on page 172 for more
information about specifying connection information for primary and
alternate servers

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

243

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

BatchPerformanceWorkaround

{true | false}

OPTIONAL

Determines the method used to execute batch operations:


The native Sybase batch mechanism is used.

true

false

The JDBC 3.0-compliant batch mechanism is used.

In most cases, using the native Sybase batch functionality provides


significantly better performance, but the driver may not always be able to
return update counts for the batch.
The default is false.
CodePageOverride
OPTIONAL

244

Specifies the code page the driver uses when converting character data.
The specified code page overrides the default database code page. All
character data retrieved from or written to the database is converted using
the specified code page. The value must be a string containing the name
of a valid code page supported by your Java Virtual Machine, for
example, CodePageOverride=CP950.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase
Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connections to a list of database


servers (primary and alternate) until a successful connection is
established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry a connection to the list of database
servers if a connection is not established on the drivers first pass through
the list.
The default is 0.
For example, in the case where the following properties are specified:
AlternateServers=(server2:4100,server3:4100,server4:4100)

and
ConnectionRetryCount=1

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries all the servers in the
list only once.
If an application sets a login timeout value, the login timeout takes
precedence over this property. For example, if the login timeout expires,
any connection attempts to alternate servers stop.
If the LoadBalancing property is set to true, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
The ConnectionRetryDelay property specifies the wait interval, in
seconds, used between attempts.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

245

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

ConnectionRetryDelay

The number of seconds the driver waits before retrying connections to a


list of database servers (primary and alternate) when
ConnectionRetryCount is set to a positive integer.

OPTIONAL

The default is 3.
For example, in the case where the following properties are specified:
AlternateServers=(server2:4100,server3:4100,server4:4100)

and
ConnectionRetryCount=2

and
ConnectionRetryDelay=3

if a connection is not successfully established on the drivers first pass


through the list of database servers, the driver retries the list of servers
twice. It waits 3 seconds between the first connection retry attempt and
the second connection retry attempt.
If the LoadBalancing property is set to true, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.
DatabaseName

The name of the database to which you want to connect.

OPTIONAL
DiagnosticFilename
OPTIONAL

The path and filename of the file to which you want state information
logged when an exception is generated. If the file does not already exist,
it will be created the first time state information is generated. If this
property is not specified, state information is not logged. When you
contact Technical Support with a problem, you might be asked to
generate a state information log.
Your application should ensure that the driver is granted read/write
permission to the specified file.

246

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase
Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

InsensitiveResultSetBufferSize

{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive


result set data. It must have one of the following values:

The driver caches all insensitive result set data in memory. If


the size of the result set exceeds available memory, an
OutOfMemoryException is generated. Because the need to write result
set data to disk is eliminated, the driver processes the data more
efficiently.

0 The driver caches all insensitive result set data in memory, up to

-1

a maximum of 2 GB. If the size of the result set data exceeds


available memory, the driver pages the result set data to disk.
Because result set data may be written to disk, the driver may have
to reformat the data to write it correctly to disk.

x, where x is a positive integer The driver caches all insensitive


result set data in memory, using this value to set the size (in KB) of
the memory buffer for caching insensitive result set data. If the size
of the result set data exceeds the buffer size, the driver pages the
result set data to disk. Because the result set data may be written to
disk, the driver may have to reformat the data to write it correctly to
disk. Specifying a buffer size that is a power of 2 results in more
efficient memory use.

The default is 2048 (KB).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

247

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

LoadBalancing

{true | false}

OPTIONAL

Determines whether the driver will use client load balancing in its
attempts to connect to a list of database servers (primary and alternate).
The list of alternate servers is specified by the AlternateServers
property. The LoadBalancing property determines behavior as follows:

true Client load balancing is used and the driver attempts to


connect to the list of database servers (primary and alternate servers)
in random order.

false Client load balancing is not used and the driver connects to

each server based on their sequential order (primary server first,


then, alternate servers in the order they are specified).
The default is false.
For example, in the case where the following properties are specified:
AlternateServers=(server2:4100,server3:4100,server4:4100)

and
LoadBalancing=true

the driver randomly selects from the list of primary and alternate servers
which server to connect to first. If that connection fails, the driver again
randomly selects from this list of servers until all servers in the list have
been tried or a connection is successfully established.
See Client Load Balancing on page 168 for more information about
specifying connection information for primary and alternate servers.

248

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase
Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

MaxPooledStatements

The maximum number of pooled prepared statements for this connection.


MaxPooledStatements property values determine behavior as follows:

OPTIONAL

An integer greater than zero (0) Enables the Sybase drivers


internal prepared statement pooling, which is useful when the driver
is not running from within an application server or another
application that provides its own prepared statement pooling. The
driver uses this value to cache a certain number of prepared
statements created by an application. For example, if the value of this
property is set to 20, the driver caches the last 20 prepared statements
created by the application.

A value greater than the number of prepared statements used by the


application All prepared statements created by the application are
cached.

Because CallableStatement is a sub-class of PreparedStatement,


are pooled.

CallableStatements also

The default is 0.
Password

The case-sensitive password used to connect to your Sybase database. A


password is required only if security is enabled on your database. If so,
contact your system administrator to get your password.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

249

Chapter 9: Driver Connection Properties and Data Types by Database Brand


Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

PrepareMethod

{StoredProc | StoredProclfParam | Direct}

OPTIONAL

Determines whether stored procedures are created on the server for


prepared statements:

StoredProc

A stored procedure is created when the statement is


prepared and is executed when the prepared statement is executed.

StoredProcIfParam

Direct

A stored procedure is created only if the


prepared statement contains one or multiple parameter markers. In
this case, it is created when the statement is prepared and is executed
when the prepared statement is executed. If the statement does not
contain parameter markers, a stored procedure is not created and the
statement is executed directly.
A stored procedure is not created for the prepared
statement and the statement is executed directly. A stored procedure
might be created if parameter metadata is requested.

The default is StoredProclfParam.


Setting this property to StoredProc or StoredProclfParam can improve
performance if your application executes prepared statements multiple
times because, once created, executing a stored procedure is faster than
executing a single database query. If a prepared statement is only
executed once or is never executed, performance can decrease because
creating a stored procedure incurs more overhead on the server than
simply executing a single database query. Setting this property to Direct
should be used if your application does not execute prepared statements
multiple times.

250

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase
Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

SelectMethod

{Direct | Cursor}

OPTIONAL

A hint to the driver that determines whether the driver requests a database
cursor for Select statements. Performance and behavior of the driver are
affected by this property, which is defined as a hint because the driver
may not always be able to satisfy the requested method.
When the driver uses the Direct method, the database
server sends the complete result set in a single response to the driver
when responding to a query. A server-side database cursor is not
created. Typically, responses are not cached by the driver. Using this
method, the driver must process all the response to a query before
another query is submitted. If another query is submitted (using a
different statement on the same connection, for example), the driver
caches the response to the first query before submitting the second
query. Typically, the Direct method performs better than the Cursor
method.

Direct

Cursor

When the driver uses the Cursor method, a server-side


database cursor is requested. The rows are retrieved from the server
in blocks when returning forward-only result sets. The JDBC
Statement method setFetchSize can be used to control the number
of rows that are retrieved for each request. Performance tests show
that the value of setFetchSize significantly impacts performance
when the Cursor method is used. There is no simple rule for
determining the setFetchSize value that you should use. We
recommend that you experiment with different setFetchSize values
to find out which value gives the best performance for your
application. The Cursor method is useful for queries that produce a
large amount of data, particularly if multiple open result sets are
used.

The default is Direct.


User

The case-insensitive user name used to connect to your Sybase database.


A user name is required only if security is enabled on your database. If
so, contact your system administrator to get your user name.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

251

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Sybase Driver Connection Failover Properties


Table 25 summarizes the connection properties that control how connection failover
works with the Database Service Sybase driver. See Table 24 for details about configuring
each property.
Table 25. Connection Failover Properties for the Sybase Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each


server is required. Port number and the DatabaseName connection property are
optional. If the port number is unspecified, the port number specified for the primary
server is used. If a port number is unspecified for the primary server, the port number
specified for the primary server is used.

ConnectionRetryCount

Number of times the driver retries the list of database servers (primary and alternate)
until a successful connection is established. The default is 0 (connection retry is not
used).

ConnectionRetryDelay

Wait interval, in seconds, used between attempts to connect to a list of database


servers (primary and alternate) when the ConnectionRetryCount property is set to a
positive integer. The default is 3.

DatabaseName

The name of the database to which you want to connect.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is disabled).

See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.

Specifying Alternate Servers for the Sybase Driver


The following connection URL for the Sybase driver specifies connection information for
the primary and alternate servers:
jdbc:sonic:sybase://server1:4100;DatabaseName=TEST;
AlternateServers=(server2:4100;DatabaseName=TEST2,server3:4100;
DatabaseName=TEST3)

252

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase

In this example:
....server1:4100;DatabaseName=TEST...

is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property, in this
example:
...;AlternateServers=(server2:4100;DatabaseName=TEST2,
server3:4100;DatabaseName=TEST3)

The property property=value is optional for each alternate server entry. For example:
jdbc:sonic:sybase://server1:4100;DatabaseName=TEST;
AlternateServers=(server2:4100;DatabaseName=TEST2,server3:4100)

If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL for the primary
server. For example, if you specify DatabaseName=TEST for the primary server, but do not
specify a database name in the alternate server entry as shown in the following URL, the
driver tries to connect to the TEST database on the alternate server:
jjdbc:sonic:sybase://server1:4100;DatabaseName=TEST;
AlternateServers=(server2:4100,server3:4100)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

253

Chapter 9: Driver Connection Properties and Data Types by Database Brand

Sybase Driver Data Types


Table 26 lists the data types supported by the Sybase driver and describes how they are
mapped to JDBC data types.
Table 26. Sybase Driver Data Types

254

Sybase DataBase

Sybase Data Type

JDBC Data Type

Sybase 11.5 and higher

binary

BINARY

bit

BIT

char

CHAR

datetime

TIMESTAMP

decimal

DECIMAL

decimal() identity

DECIMAL

float

FLOAT

image

LONGVARBINARY

int

INTEGER

money

DECIMAL

nchar

CHAR

numeric

NUMERIC

nvarchar

VARCHAR

real

REAL

smalldatetime

TIMESTAMP

smallint

SMALLINT

smallmoney

DECIMAL

sysname

VARCHAR

text

LONGVARCHAR

timestamp

VARBINARY

tinyint

TINYINT

varbinary

VARBINARY

varchar

VARCHAR

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Sybase
Table 26. Sybase Driver Data Types (continued)

Sybase DataBase

Sybase Data Type

JDBC Data Type

Sybase 12.5 and 12.5.1 only

date

DATE

time

TIME

unichar

CHAR

univarchar

VARCHAR

Note For users of Adaptive Server 12.5 and 12.5.1: The Sybase driver supports extended new

limits (XNL) for character and binary columnscolumns with lengths greater than 255.
Refer to your Sybase documentation for more information about XNL for character and
binary columns.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

255

Chapter 9: Driver Connection Properties and Data Types by Database Brand

256

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 10

SQL Escape Sequences for JDBC

Language features, such as outer joins and scalar function calls, are commonly
implemented by database systems. The syntax for these features is often databasespecific, even when a standard syntax has been defined. This chappter describes the
JDBC-defined escape sequences containing standard syntaxes for the following language
features:

Date, Time, and Timestamp Escape Sequences

Scalar Functions

Outer Join Escape Sequences

Procedure Call Escape Sequences


The escape sequence used by JDBC is:
{extension}

The escape sequence is recognized and parsed by Progress Sonic Database Service JDBC
drivers, and replaces the escape sequences with data store-specific grammar.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

257

Chapter 10: SQL Escape Sequences for JDBC

Date, Time, and Timestamp Escape Sequences


The escape sequence for date, time, and timestamp literals is:
{literal-type 'value'}

where literal-type is one of the following:


literal-type

Description

Value Format

Date

yyyy-mm-dd

Time

h:mm:ss [1]

ts

Timestamp

yyyy-mm-dd hh:mm:ss[.f...]

For example:
UPDATE Orders SET OpenDate={d '1995-01-15'}
WHERE OrderID=1023

Scalar Functions
You can use scalar functions in database queries with the following syntax:
{fn scalar-function}

where scalar-function is a scalar function supported by Database Service JDBC drivers,


as listed in Table 27.
For example:
SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}

258

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Scalar Functions
Table 27. Scalar Functions Supported by Database Service JDBC Drivers

Data Store

String Functions

Numeric
Functions

Timedate
Functions

System
Functions

Progress
OpenEdge

CONCAT

ABS

CURRDATE

DATABASE

LEFT

ACOS

CURRTIME

USER

LENGTH

ASIN

DAYOFMONTH

LTRIM

ATAN

DAYOFWEEK

REPLACE

ATAN2

MONTH

RTRIM

COS

NOW

SUBSTRING

COT

TIMESTAMP

EXP

TIMESTAMPADD

FLOOR

TIMESTAMPDIFF

LOG

YEAR

LOG10
MOD
POWER
ROUND
SIN
SQRT
TAN
TRUNCATE

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

259

Chapter 10: SQL Escape Sequences for JDBC


Table 27. Scalar Functions Supported by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric
Functions

Timedate
Functions

System
Functions

DB2

ASCII

ABS or ABSVAL

DATE

COALESCE

BLOB

ACOS

DAY

DEREF

CHAR

ASIN

DAYNAME

DLCOMMENT

CHR

ATAN

DAYOFWEEK

DLLINKTYPE

CLOB

ATANH

DAYOFYEAR

DLURLCOMPLETE

CONCAT

ATAN2

DAYS

DLURLPATH

DBCLOB

BIGINT

HOUR

DLURLPATHONLY

DIFFERENCE

CEILING or CEIL

JULIAN_DAY

DLURLSCHEME

GRAPHIC

COS

MICROSECOND

DLURLSERVER

HEX

COSH

MIDNIGHT_SECONDS

DLVALUE

INSERT

COT

MINUTE

EVENT_MON_STATE

LCASE or LOWER

DECIMAL

MONTH

GENERATE_UNIQUE

LCASE (SYSFUN schema)

DEGREES

MONTHNAME

NODENUMBER

LEFT

DIGITS

QUARTER

NULLIF

LENGTH

DOUBLE

SECOND

PARTITION

LOCATE

EXP

TIME

RAISE_ERROR

LONG_VARCHAR

FLOAT

TIMESTAMP

TABLE_NAME

LONG_VARGRAPHIC

FLOOR

TIMESTAMP_ISO

TABLE_SCHEMA

LTRIM

INTEGER

TIMESTAMPDIFF

TRANSLATE

LTRIM (SYSFUN schema)

LN

WEEK

TYPE_ID

POSSTR

LOG

YEAR

TYPE_NAME

REPEAT

LOG10

TYPE_SCHEMA

REPLACE

MOD

VALUE

RIGHT

POWER

RTRIM

RADIANS

RTRIM (SYSFUN schema)

RAND

SOUNDEX

REAL

SPACE

ROUND

SUBSTR

SIGN

TRUNCATE or TRUNC

SIN

UCASE or UPPER

SINH

VARCHAR

SMALLINT

VARGRAPHIC

SQRT
TAN
TANH
TRUNCATE

260

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Scalar Functions
Table 27. Scalar Functions Supported by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric
Functions

Timedate
Functions

System
Functions

Informix

CONCAT

ABS

CURDATE

DATABASE

LEFT

ACOS

CURTIME

USER

LENGTH

ASIN

DAYOFMONTH

LTRIM

ATAN

DAYOFWEEK

REPLACE

ATAN2

MONTH

RTRIM

COS

NOW

SUBSTRING

COT

TIMESTAMPADD

EXP

TIMESTAMPDIFF

FLOOR

YEAR

LOG
LOG10
MOD
PI
POWER
ROUND
SIN
SQRT
TAN
TRUNCATE

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

261

Chapter 10: SQL Escape Sequences for JDBC


Table 27. Scalar Functions Supported by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric
Functions

Timedate
Functions

System
Functions

Oracle

ASCII

ABS

CURDATE

IFNULL

BIT_LENGTH

ACOS

DAYNAME

USER

CHAR

ASIN

DAYOFMONTH

CONCAT

ATAN

DAYOFWEEK

INSERT

ATAN2

DAYOFYEAR

LCASE

CEILING

HOUR

LEFT

COS

MINUTE

LENGTH

COT

MONTH

LOCATE

EXP

MONTHNAME

LOCATE2

FLOOR

NOW

LTRIM

LOG

QUARTER

OCTET_LENGTH

LOG10

SECOND

REPEAT

MOD

WEEK

REPLACE

PI

YEAR

RIGHT

POWER

RTRIM

ROUND

SOUNDEX

SIGN

SPACE

SIN

SUBSTRING

SQRT

UCASE

TAN
TRUNCATE

262

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Scalar Functions
Table 27. Scalar Functions Supported by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric
Functions

Timedate
Functions

System
Functions

Microsoft
SQL Server

ASCII

ABS

DAYNAME

DATABASE

CHAR

ACOS

DAYOFMONTH

IFNULL

CONCAT

ASIN

DAYOFWEEK

USER

DIFFERENCE

ATAN

DAYOFYEAR

INSERT

ATAN2

EXTRACT

LCASE

CEILING

HOUR

LEFT

COS

MINUTE

LENGTH

COT

MONTH

LOCATE

DEGREES

MONTHNAME

LTRIM

EXP

NOW

REPEAT

FLOOR

QUARTER

REPLACE

LOG

SECOND

RIGHT

LOG10

TIMESTAMPADD

RTRIM

MOD

TIMESTAMPDIFF

SOUNDEX

PI

WEEK

SPACE

POWER

YEAR

SUBSTRING

RADIANS

UCASE

RAND
ROUND
SIGN
SIN
SQRT
TAN
TRUNCATE

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

263

Chapter 10: SQL Escape Sequences for JDBC


Table 27. Scalar Functions Supported by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric
Functions

Timedate
Functions

System
Functions

Sybase

ASCII

ABS

DAYNAME

DATABASE

CHAR

ACOS

DAYOFMONTH

IFNULL

CONCAT

ASIN

DAYOFWEEK

USER

DIFFERENCE

ATAN

DAYOFYEAR

INSERT

ATAN2

HOUR

LCASE

CEILING

MINUTE

LEFT

COS

MONTH

LENGTH

COT

MONTHNAME

LOCATE

DEGREES

NOW

LTRIM

EXP

QUARTER

REPEAT

FLOOR

SECOND

RIGHT

LOG

TIMESTAMPADD

RTRIM

LOG10

TIMESTAMPDIFF

SOUNDEX

MOD

WEEK

SPACE

PI

YEAR

SUBSTRING

POWER

UCASE

RADIANS
RAND
ROUND
SIGN
SIN
SQRT
TAN

264

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Outer Join Escape Sequences

Outer Join Escape Sequences


JDBC supports the SQL92 left, right, and full outer join syntax. The escape sequence for
outer joins is:
{oj outer-join}

where outer-join is:


table-reference {LEFT | RIGHT | FULL} OUTER JOIN
{table-reference | outer-join} ON search-condition

where:
table-reference is

a database table name


search-condition is the join condition you want to use for the tables
For example:
SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status
FROM {oj Customers LEFT OUTER JOIN
Orders ON Customers.CustID=Orders.CustID}
WHERE Orders.Status='OPEN'

Table 28 lists the outer join escape sequences supported by Database Service JDBC
drivers for each data store.
Table 28. Outer Join Sequences Supported by Database Service JDBC Drivers

Data Store

Outer Join Escape Sequences

Progress OpenEdge

Left outer joins


Right outer joins
Nested outer joins

DB2

Left outer joins


Right outer joins
Nested outer joins

Informix

Left outer joins


Right outer joins
Nested outer joins

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

265

Chapter 10: SQL Escape Sequences for JDBC


Table 28. Outer Join Sequences Supported by Database Service JDBC Drivers

Data Store

Outer Join Escape Sequences

Oracle

Left outer joins


Right outer joins
Nested outer joins

Microsoft SQL Server

Left outer joins


Right outer joins
Full outer joins
Nested outer joins

Sybase

Left outer joins


Right outer joins
Nested outer joins

Procedure Call Escape Sequences


A procedure is an executable object stored in the data store. Generally, it is one or more
database queries that have been precompiled. The escape sequence for calling a procedure
is:
{[?=]call procedure-name[(parameter[,parameter]...)]}

where:
specifies the name of a stored procedure
parameter specifies a stored procedure parameter
procedure-name

Note For DB2, a schema name cannot be used when calling a stored procedure. Also, for DB2

UDB 8.1, literal parameter values are supported for stored procedures. Other supported
DB2 versions do not support literal parameter values for stored procedures.

266

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 11

Configuring SQL Server


Windows Authentication

The Progress Sonic Database Service JDBC SQL Server driver supports Windows
authenticated connections to Microsoft SQL Server 2000 and Microsoft SQL Server 2000
Enterprise Edition (64-bit) in a domain running Windows Active Directory for Windows
clients.
See Table 29 for a summary of the configuration that is required to use Windows
authentication on Microsoft SQL Server with the Database Service JDBC SQL Server
driver.
Table 29. Configuring Windows Authentication on Microsoft SQL Server

Component

Collection

Microsoft SQL Server


Database Server

Set the authentication mode (seeSetting the Authentication Mode on page 268).
Confirm that a Service Principal Name (SPN) is registered for each Microsoft SQL
Server instance (see Registering Service Principal Names (SPNs) on page 268).

Domain Controller

Confirm that the Active Directory encryption property is set to use DES encryption
in the Microsoft SQL Server Service Startup Account (see Setting the Active
Directory Encryption Property on page 269).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

267

Chapter 11: Configuring SQL Server Windows Authentication

Setting the Authentication Mode


To use Windows authentication, the authentication mode in Microsoft SQL Server on the
database server can be set to either Windows Only authentication or Mixed authentication.
If SQL Server authentication will be used in addition to Windows authentication, set the
authentication mode to use Mixed authentication.

Registering Service Principal Names (SPNs)


An SPN must be registered for each Microsoft SQL Server instance. An SPN is a unique
name that maps the Microsoft SQL Server service for a particular machine and port to an
account name used to start the service (Service Startup Account). An SPN is composed
of a service class name of MSSQLSvc, the host name of the machine running Microsoft SQL
Server, and the port number on which the Microsoft SQL Server instance is listening. For
example:
MSSQLSvc/DBServer.test:1433

is an SPN for a Microsoft SQL Server instance running on a machine named DBServer in
the test domain and listening on port 1433.
Check with your system administrator to confirm that the appropriate SPNs have been
registered for each Microsoft SQL Server instance. To list registered SPNs, use the
following Windows command:
ldifde

If necessary, your system administrator can register SPNs using the Setspn tool available
with the Windows Resource Kit. For example:
setspn -A MSSQLSvc/DBServer.test:1433 sqlsvc

registers an SPN that maps the Service Startup Account named sqlsvc to a Microsoft SQL
Server instance running on a machine named DBServer in the test domain and listening on
port 1433. The Setspn tool is available from the following Web site:
http://www.microsoft.com/windows2000/techinfo/reskit/tools/
existing/setspn-o.asp

Refer to the Microsoft documentation accompanying the Setspn tool for instructions on
using it.
Note If the Microsoft SQL Server Service Startup Account is changed, SPNs for Microsoft

SQL Server must be deleted and re-registered.

268

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Setting the Active Directory Encryption Property

Setting the Active Directory Encryption Property


A Windows domain running Windows Active Directory uses the Kerberos authentication
protocol to protect logon credentials that travel across the network. Messages passed
between the Kerberos Key Distribution Center (KDC), which runs on every domain
controller as part of Active Directory, and Microsoft SQL Server are encrypted.
The Active Directory property "Use DES encryption types for this account" must be
set in the Microsoft SQL Server Service Startup Account on the domain controller.
Setting this property is a one-time task that you must do only when the Active Directory
account is first created. Check with your system administrator to verify that this property
is set for the Microsoft SQL Server Service Startup Account on the domain controller.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

269

Chapter 11: Configuring SQL Server Windows Authentication

270

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Part IV

Configuring and Managing BPEL Services

Part IV explains how to configure and manage BPEL services using the Sonic
Management Console, and contains the following chapters:

Configuring BPEL Services

Managing BPEL Services

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

271

272

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 12

Configuring BPEL Services

This chapter describes how to configure BPEL services using the Sonic Management
Console. This chapter contains the following sections:

Overview of BPEL Service Initialization Parameters

Specifying a BPEL Archive (.bpar)

Setting Persistence Options

Enabling Audit Trails

Audit Trails and Persistence

Setting a Default Partner Link

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

273

Chapter 12: Configuring BPEL Services

Overview of BPEL Service Initialization Parameters


A BPEL project contains a single BPEL service and one or more BPEL processes. A
BPEL service can execute a single BPEL process or multiple processes. This chapter
explains how to configure BPEL services using the Sonic Management Console (SMC).
(See the Progress Sonic BPEL Server Developers Guide in the Sonic Workbench
(Eclipse) help for detailed information about BPEL services and processes.)
Note In the development environment, you can also configure BPEL Service parameters using

the BPEL Service editor in Sonic Workbench. See the BPEL Service Editor section of the
Sonic Workbench (Eclipse) help for information.
The BPEL service configuration pane in the SMC includes areas for viewing and
configuring Service Maintenance parameters and Initialization parameters, as shown in
this example using the sample BPEL service, LoanApproval:

274

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Overview of BPEL Service Initialization Parameters

The Service Maintenance parameters are configured as for any ESB service:

Service Name

Entry Endpoint

Exit Endpoints

Fault Endpoint

Rejected Message Endpoint

WSDL URL
The WSDL URL is exposed when BPEL processes are used directly by other services on
the ESB. Each BPEL process has a separate WSDL, which is configured in the
development environment in Sonic Workbench. For information about configuring these
parameters, see the Progress Sonic BPEL Server Developers Guide in the Sonic
Workbench (Eclipse) help.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

275

Chapter 12: Configuring BPEL Services

BPEL services have the following Initialization Parameters:


Initialization Parameter

Description

BPEL Archive

The URL of a BPEL archive file (*.bpar) located in the Sonic


file system.
Required.
See Specifying a BPEL Archive (.bpar) on page 277

Staging Directory

Enter a local file system directory where the BPAR can be


unpacked. The default value is a directory named
bpel_staging, relative to the working directory of the ESB
container in which the service is deployed (./bpel_staging).
Required.
Note: The BPEL service may delete files in this directory on
service startup.

276

Persistence

Select a value to define how the service is to persist (if at all)


its state. The default value is Embedded Storage.
Required.
See Setting Persistence Options on page 278.

Enable Audit Trail Recording

Select whether audit trails are captured for process instances.


The default value is True.
Required.
See Audit Trails and Persistence on page 283.

Default Partner Link

Specify the default process and partner link to use.


Optional.
See Setting a Default Partner Link on page 284.

HTTP Callback URL

The address used as the Reply To address when using WSA


headers in asynchronous invocations.
Optional.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Specifying a BPEL Archive (.bpar)

Specifying a BPEL Archive (.bpar)


A BPAR file (*.bpar) is an archive of all resources required to execute a set of BPEL
processes. A BPAR is created by Sonic Workbench when a BPEL project is uploaded.
When configuring a BPEL service in the SMC you must point to an existing BPAR file.
A single BPAR can be used by one more than one service. (See the Progress Sonic BPEL
Server Developers Guide in the Sonic Workbench (Eclipse) help for more information
about BPAR files.)
Note It is recommended that BPAR files be stored in the Sonic file system (sonicfs://),

however, local system paths may be specified.


To specify a BPEL archive file:
1.

In the Init Parameters area of the SMC, click ... next to the BPEL Archive field to open
the Edit BPEL Archive file chooser, as shown in this example:

2.

Browse to and select a BPEL archive file (*.bpar).

3.

Click Open.
The URL of the BPEL archive file is now displayed in the BPEL Archive field of the
SMC.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

277

Chapter 12: Configuring BPEL Services

Setting Persistence Options


Persistence refers to the storage of active processes deployed to a server. Engine
persistence must be configured to allow persistent processes and audit trails (see
Enabling Audit Trails on page 282). If a service is configured to allow persistence, each
process can then be configured to utilize it or not using its deployment descriptor file
(*.bpdd). See the BPEL Deployment Descriptor editor section of the Progress Sonic
BPEL Server Developers Guide in the Sonic Workbench (Eclipse) help for information.
BPEL services can run in either of two process modes:

Persistent process mode: In this mode, BPEL process instances can have their
lifetimes persist across container lifetime. All state information is stored in the server
database. The persistent processes are supported by either the embedded Hypersonic
database, or an external database (either MySQL or Oracle).
To select this mode, select the configuration option Embedded Storage (Hypersonic
database) or Other Database (MySQL or Oracle) option for the persistence.
The default process mode for BPEL services is Embedded Storage (Hypersonic
database).
When using an external database, each BPEL service instance must be configured
with its own database. (Multiple databases can be created on the same server.) When
using the embedded database, the service manages a separate instance for each
service instance.

Important

Transient process mode: In this mode, processes that have not completed when the
service container is shut down are terminated at shutdown. No process information is
stored in the server database when a process terminates.
To select this mode, select the In Memory configuration option for the persistence.

A BPEL service must be configured with persistence to allow persistence for any of the
processes deployed in it. Deploying persistent processes into a service configured in
transient mode effectively disables persistence for the process. Service and process
persistence modes are summarized in the following table:

278

Service

Process

Persistent

Can be Persistent or Transient, as


configured for the process.

Transient

Always Transient, regardless of process


configuration.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Setting Persistence Options

The following procedure explains how to set the persistence for a BPEL service using the
SMC.
To set persistence for a BPEL service:
1.

In the Init Parameters area of the SMC, click ... next to the Persistence field. The
Persistence Editor dialog box opens:

Embedded Storage is the default persistence setting.


2.

Select the Data Source Type, either:

In Memory This option sets the persistence mode to transient. When you select
this option, the Persistence field in the Init Parameters section of the SMC will
display the value In Memory.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

279

Chapter 12: Configuring BPEL Services

Embedded Storage This option sets the persistence mode to persistent, using

the embedded Hypersonic database. Optionally, you can specify a storage


directory for the persistent processes. If you do not specify a storage directory, the
default is the staging directory. The database is created as needed in the specified
storage directory when the service starts. If you move or delete the database, a
new database is created the next time the service starts. Existing databases in the
staging directory are deleted (on service restart) when you specify a new storage
location.
When you select Embedded Storage, the Persistence field in the Init Parameters
section of the SMC will display the value Embedded Storage.
(This is the default mode.)
Other Database This option sets the persistence mode to persistent, using a
database other than the embedded database. When this option is selected, you
must provide additional details required to connect to the database. Only Oracle
and MySQL database types are supported (see Step 3). When you select this
option, the Persistence field in the Init Parameters section of the SMC will
display a value for the selected database type:

Oracle:
type=oracle username=username host=localhost port=1521

MySQL:
type=mysql name=dbname username=username host=localhost
port=1521

When using an external database, each BPEL service instance must be


configured with its own database.

Important

3.

If you selected Other Database as the data source type, enter the following Database
Options:

Important

280

Database Type Select either Oracle or MySQL


Database Name Optional
Machine Name Optional
Database Port Optional
Username Optional
Password Optional

When using an Oracle or MySQL database, you must add the JDBC driver JAR file
to the container classpath (see Adding JAR files to an ESB Container on page 63
for instructions).

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Setting Persistence Options


4.

Click OK to set the persistence mode and close the dialog box.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

281

Chapter 12: Configuring BPEL Services

BPEL Development Container Configuration


The BPEL development container, dev_BPEL, is configured to terminate all process
instances at startup. This container uses embedded storage by default. All historical
information (terminated processes and audit trails) remains available in the database and
can be accessed through the SMC Management tab. You can safely delete the database
from the storage directory.

Enabling Audit Trails


An audit trail captures a history of the process instance as it executes. You can query and
view this history under the Manage tab in the SMC (see Viewing Audit Trails on
page 294).
Note Audit trails are only supported in persistent process mode by selecting either Embedded
Storage or Other Database for the persistence parameter (see Setting Persistence

Options on page 278).


As with persistence, you can configure audit trails for each process using its deployment
descriptor file (*.bpdd) (see the BPEL Deployment Descriptor editor section of the
Progress Sonic BPEL Server Developers Guide in the Sonic Workbench (Eclipse) help
for information). If audit trails are enabled for the service, then the per-process settings
for audit trail (if any) are used. If audit trails are disabled for the service, then the perprocess settings are ignored and audit trails are always disabled.
See Viewing Audit Trails on page 294 for information about the details you can view is
audit trails.
To enable audit trail recording:

282

In the Init Parameters area of the SMC, select True from the Enable Audit Trails pulldown list. (Selecting False disables audit trails.)

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Audit Trails and Persistence

Audit Trails and Persistence


Audit trails are stored in the database with the process instance state (when using
persistent process mode). The following modes of operation are typical:

Persistent process mode with audit trails enabled This is the standard
configuration. All current and historical process state is saved.

Non-persistent process mode with audit trails not enabled No process state is
saved. Process instances do not survive a container restart and support only limited
management capabilities. This mode is useful for short-duration processes where
performance is more important than recoverability.

Persistent process mode with audit trails not enabled Only the current process state
is saved. This mode is useful to limit database growth, particularly with processes that
might generate very long histories. Note that without audit trails the management
capabilities are limited.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

283

Chapter 12: Configuring BPEL Services

Setting a Default Partner Link


When a BPEL Service is invoked it uses WS-Addressing reference parameters to identify
the process and partner link associated with the invocation. If the message does not
specify this information then the default process and partner link are used.
The default partner link is optional. If no default is specified and the service cannot
determine the process and partner link from the invocation message, the service will
produce a fault.
The processes (and partner links) in the Edit Default Partner Link dialog box are obtained
from the BPEL archive, so you must specify the archive before you can edit the default
partner link.
You can set or edit the default partner link for a BPEL service when configuring the
service in the SMC.
To set or edit the default partner link:
1.

In the Init Parameters area of the SMC, click ... to the right of the Default Partner Link
field. The Default Partner Link dialog box opens, as shown in this example:

If the BPEL service does not have any partner link configured, then the dialog box
displays the value None.

284

2.

Select the Process and Partner Link for the BPEL service from the pull-down lists of
processes and partner links.

3.

To remove a partner link, click Clear.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Considerations with Dehydrated Processes

Considerations with Dehydrated Processes


With dehydration, Sonic BPEL Server stores the process and its state in the database while
waiting for a response, thus freeing up server resources. Hydration occurs when the
engine receives the response and restores the process and its state from the database and
continues executing the process.
Process instances cannot be dehydrated unless the following conditions are met:

You are not in development mode (TEST_CONTAINER_MODE is not set, or set to FALSE).
(See Setting Test Mode for ESB Containers Used in Development on page 62.)

You are using a Persistent store (that is, not In Memory). (See Setting Persistence
Options on page 278.)

All activities must be in a waiting state (that is, no alerts are set).

There are no synchronous inbound connections.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

285

Chapter 12: Configuring BPEL Services

286

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Chapter 13

Managing BPEL Services

This chapter describes how to manage BPEL services. This chapter contains the following
sections:

Overview of BPEL Service and Process Management

Clearing Process History

Terminating Processes

Searching for Process Instances

Viewing Audit Trails

BPEL Profiling

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

287

Chapter 13: Managing BPEL Services

Overview of BPEL Service and Process Management


Under the Manage tab in the Sonic Management Console (SMC), you can view BPEL
services in ESB containers and perform management operations. You can also view and
manage all BPEL processes for each BPEL service.
To view and manage BPEL services and processes in the SMC:

In the left pane of the SMC under the Manage tab, select a BPEL service and view the
associated processes in the right pane. In this example, selecting the sample BPEL
service LoanApproval in the left pane displays the processes loanAssessor,
pubSubApproval, and loanApproval in the right pane:

Management operations can be performed on all the processes in a BPEL service when
executed on the right pane, or on a specific process when executed in the left pane. For
example, right-clicking a service in the left pane and selecting Terminate All terminates
all instances of all processes for that service. Right-clicking a process in the right pane
and selecting Terminate All terminates only instances of the selected process.

288

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Clearing Process History

The SMC provides the following management capabilities for BPEL services and
processes:

Clear history for a process or for all processes in a service (see Clearing Process
History on page 289).

Terminate a process or all processes in a service (see Terminating Processes on


page 290).

Search for a set of process instances that match your specified criteria (see Searching
for Process Instances on page 290).

View audit trails for a selected process instance (see Viewing Audit Trails on
page 294).

View aggregate information for all the process instances created by a selected process
(see BPEL Profiling on page 296).

Clearing Process History


You can clear the history for a single process (for all its expired instances) or for all
processes in a service. Clearing the history removes audit trails and terminated process
instances.
To clear process history:
1.

To clear the process history for all processes in a service, right-click on a BPEL
service (in the left pane) and select Clear History. The Clear History dialog box opens:

Select whether to remove only processes that ended on or before a cutoff date (you
must specify the date), or to remove all processes.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

289

Chapter 13: Managing BPEL Services


2.

To clear the process history for a selected process, right-click on a BPEL process (in
the right pane) and select Clear History. The Clear History dialog box opens:

Select whether to remove only instances of the selected process that ended on or
before a cutoff date (you must specify the date), or to remove all instances of the
selected process.

Terminating Processes
You can terminate a single process or all processes in a service.
To terminate processes:
1.

To terminate all processes in a service, right-click on a BPEL service (in the left
pane) and select Terminate All. This action terminates all live instances of all the
processes listed for the BPEL service.

2.

To terminate a selected process, right-click on a BPEL process (in the right pane) and
select Terminate All. This action terminates all live instances of the selected process.

Searching for Process Instances


You can use Process Instance Search tool to find instances of a process that match a set
of criteria. You can specify the following search criteria:

Process instance state (live, terminated, or either)

Start or termination time

Received or sent message parts

XPath expressions, which include access to process variables


Note If you search for all instances of a process, you cannot also select a start or termination

time.

290

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Searching for Process Instances

The following procedure explains how to search for BPEL process instances using the
Process Instance Search tool in the SMC.
To search for BPEL process instances:
1.

In the Manage tab of the SMC, select a BPEL service in the left pane, then select a
BPEL process in the right pane. In the lower right pane, click Search. The Process
Instance Search window opens, as shown in this example using the sample BPEL
process, pubSubApproval:

2.

In the Search Criteria section specify a Search Filter:

All Instances

Live Instances
Terminated Instances

Note

If you select All Instances of a process, you cannot also select a start or termination
time.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

291

Chapter 13: Managing BPEL Services


3.

4.

Optionally, in the Date section, enter a date and time in either or both the Started After
and Terminated Before fields.
When the Date is specified, a search returns processes as follows for different Search
Filter selections:
Search Filter

Processes Returned by Search

All Instances

The Started After and Terminated Before fields are disabled when
All Instances is selected.

Live Instances

Returns processes that started between the times specified in the


fields Started After and Terminated Before.

Terminated Only

Returns processes that terminated between the times specified in


the fields Started After and Terminated Before.

Optionally, in the Messages section, click Add to specify the following search criteria
in the table:

Destination Select Any, Inbound, or Outbound (Required)

If you specify an asterisk (*) as the value for any of the criteria, that value is ignored.

Note
5.

Note

292

Message Namespace
Message Local Name
Part
Search Value

Optionally, in the Boolean XPath Expressions section, click Add to specify the
comparison of a BPEL variable. The following expressions allow access to variables
and their properties:
Variable

Description

$variableName

The value of the variable.

bpws:getVariableProperty(name,property)

The value of the property with respect


to the variable identified.

The properties must be specified as namespace qualified identities. The


namespace prefixes available are those defined in the BPEL process (see the
Progress Sonic BPEL Server Developers Guide in the Sonic Workbench
(Eclipse) help for information about defining namespaces in a BPEL process).
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Searching for Process Instances

Specifying an XPath expression enables you to select process instances based on


variable values and conditions applied to them. The conditions are expressed as XPath
2.0 expressions.
6.

Click Search. The search results are displayed in the Process Instance Search
Results section, as shown in this example:

The search results are a list of process instances satisfying your search criteria with
the following column values:

Process ID The unique ID of the process instance

Terminated The date, if terminated, or live.

Correlation (if correlation set(s) are defined for the process) Zero or more
columns. Each correlation set is potentially an array of properties. The column
name is the correlation set name and the value is a comma separated list of
property values. For example:
Property1=value,Property2=value

The correlation column is dynamic, and is only shown when a process has
correlation values.

Note

7.

To terminate a process instance, select the instance in the Process Instance Results
section and click Terminate.

8.

To view the audit trail of a process instance, select the instance in the Process
Instance Results section and click Audit Trail. (See Viewing Audit Trails on
page 294.)

9.

Close the Process Instance Search window to return to the SMC.

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

293

Chapter 13: Managing BPEL Services

Viewing Audit Trails


When a BPEL service configuration has the Enable Audit Trails option set to True (see
Audit Trails and Persistence on page 283) and the Persistence option set to something
other than In Memory (see Setting Persistence Options on page 278), you can view
activities and event details of a BPEL process instance.
To view audit trails and event details:
1.

294

In the Search Process Instance window, select a process instance and click Audit
Trail (see Searching for Process Instances on page 290). The Audit Trail dialog box
opens and displays the audit trail for the selected process instance, as shown in this
example using the sample BPEL process, loanApproval:

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Viewing Audit Trails

The Audit Events pane displays the following information:

Activity Type

Activity XML:ID The value of the ID attribute in the processs XML document

Activity ID A unique number for the specific instance of the activity. When

multiple audit events are logged for the same activity, this number can be used to
correlate all related events. (For example, see Activity ID 27 in the preceding
example.)
Time The time, including date, at which the activity was recorded.

Many activities generate multiple audit trail events. For instance, many activities
generate a START event and a COMPLETE event, as in the preceding example.

Note

2.

Select an activity in the left pane. If the activity has additional details, the details of
the selected activity are displayed in the Events Details pane, as shown in this
example:

Event details include the following information, depending on the selected activity:

Messages received by a RECEIVE activity

Messages sent by an INVOKE activity

Variable manipulation performed by an ASSIGN activity

Fault information
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

295

Chapter 13: Managing BPEL Services

BPEL Profiling
You can view the activities of a BPEL process in the BPEL Profile dialog box under the
Manage tab in the SMC. This information represents aggregate performance information
of all process instances recorded for a particular process in the service. Clearing the
history (see Clearing Process History on page 289) resets the profiling information.
To view detailed activities of a BPEL process:

In the Manage tab of the SMC, select a BPEL process then click BPEL Profile. The
BPEL Profile dialog box opens, as shown in this example:

The BPEL Profile dialog box lists the activities for a process by ID, and contains the
following information:

Activity XML:ID

Activity Description, including the name attribute specified in the BPEL process,

if any

296

Times Completed: Minimum, average, and maximum [ms]

Individual time: Minimum, average, and maximum [ms]

Total time: Minimum, average, and maximum [ms]

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Index

A
action flows
tuning 133
Activation Daemon 78, 173
retry rules 81
add directory command 35
add file command 35
add license container command 39
address factory 50
address space size 136
addresses 85
alternate servers 172
DB2 186
Informix 202
Microsoft SQL Server 228
Oracle 213
Progress OpenEdge 176, 181
Sybase 243
application performance
transformation 148
XML document update 133
applyMap command 44
arguments
backup utility 156
restore utility 159

B
backing up document collections 152
backup image files 155

backup record files 155


backup utility 156
backups
full 152, 157
incremental 152, 158
scheduling 152
Blob and binary stream data (DB2) 196
boot files 51
BPAR 277
BPEL
archive file 277
audit trail 282, 294
partner link 284
process instance search 290
profiling 296
BPEL services
configuring 273
broker
Actional instrumentation 54
payload in Actional instrumentation 54

C
cache
size 138
cache resources 136
certificate-based authentication 108
cipher suites 108
clearing management container logs 67
client load balancing 168
code page

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

297

Index

converting character data


DB2 188
Informix 202
Microsoft SQL Server 229
Sybase 244
overriding
DB2 188
Informix 202
commands, ESB Admin Tool 33
commit transaction if idle 135
concurrency control and performance 130
concurrent durable subscriptions 91, 97
configuring
BPEL services 273
connections 103
SonicMQ endpoints 95
connect command 34
connecting to domain manager 20
connection
configuring 103
connection URLs 105
deleting 109
ESB 54
for endpoints 96
HTTP(S) 54
JMS 54
maximum at least once sessions 106
maximum best effort sessions 106
maximum exactly once sessions 106
maximum receive sessions 106
maximum Web Service sessions 106
name 105
name of domain 22
ping interval 107
type 105
connection failover 169
alternate servers
DB2 186
Informix 202
Microsoft SQL Server 228
Oracle 213
Progress OpenEdge 176, 181
Sybase 243
connection retry 170
ConnectionRetryCount
DB2 189
Informix 203
298

Microsoft SQL Server 230


Oracle 215
Progress OpenEdge 177, 181
Sybase 245
ConnectionRetryDelay
DB2 190
Informix 204
Microsoft SQL Server 231
Oracle 216
Progress OpenEdge 177, 181
Sybase 246
DatabaseName
Progress OpenEdge 178, 181
connection URLs
connections 105
domain 22
container list command 39
createMap command 44

D
data stores
backing up 152
restoring from backup 158
date format (Informix) 205
DB2
code page
character data, converting 188
connection properties
alternate servers 186
CodePageOverride 188
ConnectionRetryCount 189
ConnectionRetryDelay 190
DiagnosticFilename 191
InsensitiveResultSetBufferSize 192
LoadBalancing 193
MaxPooledStatements 194
ConnectionRetry 189
ConnectionRetryDelay 190
DBClob data type mapping 200
load balancing 193
scalar functions 260
state information log 191
DBDate (Informix) 205
debug tracing 75
debugging 123

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Index

delete command 36, 38


delete directory command 36
delete file command 34
deleting
SonicMQ connections 109
SonicMQ endpoints 99
stored data, performance 144
destination name for endpoints 97
DiagnosticFilename
DB2 191
Informix 206
Microsoft SQL Server 231
Oracle 216
Sybase 246
disconnect command 34
document collections
archiving 144
backing up 152
indexes 140
tuning disk storage 143
domain manager
connecting to 20
starting 20
domains
connection name 22
connection URL(s) of management broker 22
name 22
DRA, using 93
dump command 38
durable subscription, concurrent 97

E
enable Actional instrumentation
broker 54
endpoints
configuring 95
connections 96
deleting 99
durable subscription 97
entry 86
exit 86
fault 86
JMS destination name 97
JMS destination type 96

load balancing 98
message prefetch count 98
message prefetch threshold 98
name 96
priority 97
Qualify of Service 96
RME 87
shared subscriptions 98
time to live 98
WSDL URL 96
entry endpoints 86
envelope factory 50
ESB (JMS) connection 54
ESB Admin 33
ESB Admin Tool
commands 33
ESB Configured Objects 26
ESB Container
listeners 61
exit endpoint 86
export archive command 44
export bootfile command 44
export command 38
export directory command 36
export file command 36
export license container command 39

F
factory
address 50
envelope 50
message 50
objects for container services 50
failover 169
fault endpoint 86
fault tolerant client connections 99
files
backup image 155
backup record 155
log 155
transaction log 145
full backup 152, 157

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

299

Index

HTTP routing connection 54


http_defaultConnection 96

JMS destination type 96


JMS destinations 89
jms_defaultConnection 96

I
import archive command 45
import command 38
import file system command 45
incremental backup 152, 158
indexes
document collections 140
value 146
Informix
code page
character data, converting 202
connection properties
alternate servers 202
CodePageOverride 202
ConnectionRetryCount 203
ConnectionRetryDelay 204
DBDate 205
DiagnosticFilename 206
InformixServer 206
InsensitiveResultSetBufferSize 206
LoadBalancing 207
MaxPooledStatements 208
ConnectionRetry 203
ConnectionRetryDelay 204
date format 205
load balancing 207
scalar functions 261
state information log 206
InsensitiveResultSetBufferSize
DB2 192
Informix 206
Microsoft SQL Server 232
Oracle 217
Progress OpenEdge 178
Sybase 247
instrumentation payload, broker 54
instrumentation, broker 54
invalid archive address notification 121

300

L
launching management containers 66
list command 37
listener threads, tuning 135
listeners 58
listeners, number 61
load balancing 168
DB2 193
Informix 207
Microsoft SQL Server 233
Oracle 218
Sybase 248
load balancing, endpoints 98
LoadBalancing
Progress OpenEdge 179, 181
log files 155
logging 75, 123

M
management broker
connection URL(s) 22
management container logs
clearing 67
saving 67
viewing 67
management containers
launching 66
operations 66
reload command 40
resetting metrics 66
restarting 66
resume command 40
shutdown command 39
shutting down 66
status command 40
suspend command 40
maximum

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Index

at least once sessions 106


best effort sessions 106
exactly once sessions 106
receive sessions 106
Web Service sesions 106
MaxPooledStatements
DB2 194
Informix 208
Microsoft SQL Server 234
Oracle 219
Progress OpenEdge 179
Sybase 249
message
factory 50
prefetch threshold 98
message prefetch count 98
message routing tuning 141
metrics 118
Microsoft SQL Server
code page
character data, converting 229
connection properties
alternate servers 228
CodePageOverride 229
ConnectionRetryCount 230
ConnectionRetryDelay 231
DiagnosticFilename 231
InsensitiveResultSetBufferSize 232
LoadBalancing 233
MaxPooledStatements 234
ConnectionRetry 230
ConnectionRetryDelay 231
load balancing 233
scalar functions 263
state information log 231

N
names
connections 105
domain 22
endpoints 96
nonindexed XPath traversal 147
notifications 71, 121

O
operations
management containers 66
Oracle
connection properties
alternate servers 213
ConnectionRetryCount 215
ConnectionRetryDelay 216
DiagnosticFilename 216
InsensitiveResultSetBufferSize 217
LoadBalancing 218
MaxPooledStatements 219
ConnectionRetry 215
ConnectionRetryDelay 216
load balancing 218
scalar functions 262
state information log 216
outer joins 265

P
Password
Progress OpenEdge 179
payload, Actional instrumentation
broker 54
performance
action flows 133
address space management 136
archiving 144
cache affinity 138
cache resources 136
cache size management 138
commit transaction if idle 135
concurrency control 130
deleting stored data 144
indexes 140
listener threads 135
message routing tuning 141
reducing transaction deadlock 130
return set 147
transaction level 133
transaction management 130
transaction open interval 134
transformation 148
tuning disk storage 143

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

301

Index

tuning storage maintenance 144


value indexes 146
XML document update 133
XML Service 133
XPath processing 146
XPath, nonindexed traversal 147
XSLT node selection 148
XSLT output generation 149
XSLT template matching 149
ping interval, connection property 103, 107
PortNumber
Progress OpenEdge 180, 181
primary servers 172
priority
endpoints 97
Progress OpenEdge 178, 179, 180, 181
connection properties
alternate servers 176, 181
ConnectionRetryCount 177, 181
ConnectionRetryDelay 177, 181
DatabaseName 178, 181
Hostname 178
InsensitiveResultSetBufferSize 178
LoadBalancing 179, 181
MaxPooledStatements 179
Password 179
PortNumber 180, 181
SpyAttributes 180
User 180
ConnectionRetry 177, 181
ConnectionRetryDelay 181
DatabaseName 178, 181
InsensitiveResultSetBufferSize 178
LoadBalancing 179, 181
MaxPooledStatements 179
Password 179
PortNumber 180, 181
scalar functions 259
SpyAttributes 180
User 180

Q
Quality of Service, endpoints 96
queues
creating 97
302

R
reconnection 101
rejected message endpoint 87
reload command 40
resetting
management container metrics 66
resources 23
restarting
management containers 66
restoring document collections
from full backup images 160
from incremental backup images 161
resume command 40
return set 147

S
saving management container logs 67
scalar functions
DB2 260
Informix 261
Microsoft SQL Server 263
Oracle 262
Progress OpenEdge 259
Sybase 264
shared subscriptions 91
endpoints 98
shutdown container 39
shutting down management containers 66
Sonic Management Console 21
SonicFS 23
Spy (DataDirect) 180
SpyAttributes
Progress OpenEdge 180
SSL
CA certificates location 108
certificate chain file 108
certificate chain form 108
cipher suites 108
private key file 108
private key password 108
provider class 108
starting
domain manager 20

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Index

state information log


DB2 191
Informix 206
Microsoft SQL Server 231
Oracle 216
Sybase 246
support, technical 15
suspend command 40
Sybase
code page
character data, converting 244
connection properties
alternate servers 243
CodePageOverride 244
ConnectionRetryCount 245
ConnectionRetryDelay 246
DiagnosticFilename 246
InsensitiveResultSetBufferSize 247
LoadBalancing 248
MaxPooledStatements 249
ConnectionRetry 245
ConnectionRetryDelay 246
load balancing 248
scalar functions 264
state information log 246

T
technical support 15
threads, listener 61
time to live
endpoints 98
transaction level property 133
transaction log 145
transaction open interval 134
transactions
management and performance 130
transformation performance 148
tuning storage maintenance 144
type, connections 105

U
User
Progress OpenEdge 180

V
value indexes 146
viewing management container logs 67

W
Web Service sessions
maximum 106
WSDL URL
endpoints 96

X
XML document update performance 133
XML Service
address space size 136
cache size 138
tuning 133
XPath
nonindexed traversal 147
processing performance 146
XSLT
node selection 148
output generation 149
template matching 149

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

303

Index

304

Progress Sonic ESB Product Family: Configuration and Management Guide V7.6