Professional Documents
Culture Documents
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
20
21
26
33
34
35
37
39
39
40
47
Contents
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Contents
111
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Configuring WebService Protocols for ESB Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Related Configuration Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Part II:
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
Part III:
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
209
210
212
212
223
224
225
227
227
238
238
240
242
242
252
252
254
257
258
258
265
266
......................
Date, Time, and Timestamp Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scalar Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outer Join Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Procedure Call Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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:
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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
About This Guide describes this manual and its intended audience.
Progress Sonic ESB Product Family Documentation describes the books and API
online references packaged with the Sonic ESB Product Family.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
11
Preface
Part I, ESB Configuration Tools and Managed Components, includes the chapters:
Chapter 10, SQL Escape Sequences for JDBC, describes the JDBC-defined
escape sequences containing standard syntaxes for several language features.
Part IV, Configuring and Managing BPEL Services, includes the chapters:
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:
Bold monospace typeface emphasizes text that would otherwise appear in monospace
typeface to emphasize some computer input or output in context.
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
13
Preface
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 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
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
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
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
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
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
On Windows, choose:
Start > Programs > Progress > Sonic 7.6 > Sonic Management Console
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
Description
Connection Name
Domain Name
Connection URL(s)
User Name
Password
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
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
Select the Manage tab and expand Containers. The following example shows the
runtime state of several containers:
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.)
24
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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
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:
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
27
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
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.
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
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
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}
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
31
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
Select Start > Programs > Progress > Sonic 7.6 > Tools > ESB Admin Tool.
The ESB Admin Tool console window opens.
2.
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.
example, trying to connect to Domain1, yet entering domain1 will not succeed.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
33
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]
where:
disconnect
disconnect
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
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
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
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
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
list
list [type]
List the names of configurations in the domain. For example, to list the available types:
list
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
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
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
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
container status
container status container_name
Perform the specified operation on the management container and ESB Container
(a component of the management container).
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
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:
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
diff
Sonic_Diff.xml
mqdepends
Sonic_Dependency.xml
mqrevdepends
Sonic_ReverseDependency.xml
impact
Sonic_ImpactAnalysis.xml
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
41
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]
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:
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
mqrevdepends
mqrevdepends -storeType storeParams [-out outFile.xml]
[-include artifact1 [artifact2 ...] | -includeFile artifactListFile]
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]
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
43
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.
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
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.
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
45
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:
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
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
2.
3.
4.
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.
3.
4.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
47
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
49
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:
50
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Overview
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.
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:
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
51
The following events occur as the ESB Container manages message transfer:
1.
The ESB Container reads configuration information from the Directory Service.
2.
3.
4.
5.
6.
7.
Messages in the OUTBOX are sent to SonicMQ destinations by the services, or to other
services in the container.
52
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
Description
Name
Intra-container
Messaging
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.
Description
Enable Actional
Instrumentation
Enable Payload
Capture
Click Apply to complete the definition of the ESB Container you created.
54
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
56
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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:
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
57
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
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.
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
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
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.
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
60
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
4.
Important When you modify a service or process in an ESB Container, the container must be
Section
Configuring Containers
Generating Containers
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
61
62
1.
2.
3.
Click on the management container. On the right panel, right-click on the ESB
Container component, and then choose Properties.
4.
5.
In the New Deployment Parameter dialog box, enter the Name TEST_CONTAINER_MODE
and the Value true. Click OK.
6.
7.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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.
Note You usually import archives and their classpath reference during the import process of
64
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Select the Manage tab in Sonic Management Console and select the folder that
contains the management containers.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
65
You can select a management container, right click, and select Operations to:
Operation
Description
Launch
Restart
Shutdown
Reset Metrics
Invoke Diagnostics...
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
4.
You can select a management container, right click, and select Container Log to:
Operation
Description
View
Clear
Save to 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:
67
To perform operations on an ESB Container, right click on it, then select Operations:
Operation
Description
Start
Stop
Reload
Abort
Aborts the ESB container, its ESB services, and its ESB processes.
Clear Error
Reset Metrics
To perform operations on an ESB service, right click on it, then select Operations:
Operation
Description
Start
Stop
Abort
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
Standard Metrics
All ESB services deployed in an ESB container support the following metrics:
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
69
esb.service.messages.Faulted
70
1.
Open the Sonic Management Console and select the Manage tab.
2.
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
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 aborted
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
71
Open the Sonic Management Console and select the Manage tab.
2.
3.
You can select one or more notifications, and for each notification, select Watch and
select whether to watch:
By Domain
The Sonic Management Console marks notifications that are being watched:
72
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
73
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
In the Sonic Management Console, select the Manage tab and select the management
container that hosts the ESB Container.
2.
3.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
75
Select the Tracing tab and then select tracing bit masks. In this example, Verbose, Set
Attributes, and Enable Debug Messages are selected.:
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
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
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
At a configured time
78
1.
2.
3.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
6.
Click OK.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
79
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
Component
Click ... to open the Choose Component dialog box. For this example,
choose /Containers/AD_for_Services.
Auto Start
Tracing Mask
For this example, the New Container Component dialog box should look like this:
4.
80
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
2.
3.
Description
Container
Number of
Retries
Retry Interval
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
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.
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
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
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
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:
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
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.
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
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
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:
rejectedLocation The location of the failure; it can have these optional attributes:
containerName The name of the ESB Container 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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
87
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
) method:
rejectedCode = XQ_ENDPOINT_EXCEPTION
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
Will you run multiple instances of a service for scalability and reliability?
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.
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
QoS
Destination
Type
Multiple Services
AT_LEAST_ONCE
Topic
or
EXACTLY_ONCE
BEST_EFFORT
Queue
Topic
Queue
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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:
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
93
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 either:
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:
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
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
95
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.
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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
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 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
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
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.)
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.
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
Default Value
faultTolerant
False
initialConnectTimeout
30 seconds
faultTolerantReconnectTimeout
60 seconds
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
99
100
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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:
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
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
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.
Description
Connection Name
Connection Type
Connection URLs
User Name
Password
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
Description
Maximum Receive
Sessions Per
Connection
Important
106
Maximum
BEST_EFFORT
Sessions
Maximum
AT_LEAST_ONCE
Sessions
Maximum
EXACTLY_ONCE
Sessions
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.
Description
Ping Interval
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
107
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
Provides the pathname that points to the file containing the brokerencrypted private key for SSL.
Provides the password to encrypt the broker private key for SSL.
PKCS7
PKCS12
LIST
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
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.)
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.
4.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
109
110
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Chapter 4
This chapter describes how to configure Web Services using WS-* standards in the
following sections:
Overview
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
111
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.
112
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
Configurable
Element
Location
Broker
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
113
114
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Part II
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
117
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
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.
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
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:
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
system.state.Offline
system.state.Online
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
121
You can select one or more notifications, and for each notification, select Watch and
select whether to watch:
By Domain
The Sonic Management Console marks notifications that are being watched:
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:
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
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
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
125
126
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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
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
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
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
131
132
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Locking Read-only actions are serialized with respect to update actions running
in the same XML Service.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
133
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.
134
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
135
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.
136
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Increase the amount of address space allocated to the XML Service when you
configure it in the Sonic Management Console.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
137
Amount of data that is accessed XML Services that are accessing or updating
large amounts of data need larger caches.
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.
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
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:
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
139
140
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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
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
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:
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.
144
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
145
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:
Efficiency of the optimized XPath execution tree, which in turn depends on:
Data extraction, sorting, and serialization that must be done on the return set
The following suuggestions can improve XPath performance.
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
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
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
147
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.
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.
4.
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
150
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Chapter 7
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:
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
2.
Choose locations for backup-related files. See Files Generated by the Backup and
Restore Utilities on page 155.
3.
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.
152
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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:
Day
Level
Description
Sunday
0 (full)
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
153
154
Day
Level
Description
Sunday
0 (full)
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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
-meta
-service servicename
-coll collectionname
-path metadatapath
-verbose
Verbose output.
-level inc-level
-incfile inc-file
-dir backupdir
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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.
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
158
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
-meta
-service servicename
-coll collectionname
-path metadatapath
-remap
-verbose
Verbose output.
-dir backupdir
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
159
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
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.
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.
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
162
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Part III
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
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
165
166
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
Specifying Alternate Servers for the Progress OpenEdge Driver on page 182
Specifying Alternate Servers for the Microsoft SQL Server Driver on page 238
DB2
Informix
Oracle
Microsoft SQL
Server
Sybase
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
167
Database Server A
(Primary)
Database Server B
(First Alternate)
Database Server C
(Second Alternate)
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:
168
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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)
Database Server B
(First Alternate)
Database Server C
(Second Alternate)
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
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:
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
171
where:
servername2 is
172
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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 Microsoft SQL Server Driver on page 238
At a configured time
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.
2.
3.
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
174
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Chapter 9
This chapter contains driver connection properties, connection failover properties, and
driver data types for the following database brands:
DB2
Informix
Oracle
Sybase
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
175
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
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
177
Property
Description
DatabaseName
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
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.
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
Password
REQUIRED
Default: No default
Data type: String
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
179
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
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]...)
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
180
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Property
Description
AlternateServers
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
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
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
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.
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
184
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
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:
Note
All connection property names are case-insensitive. For example, Password is the same
as password.
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
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
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:
retry attempts.
LoadBalancing
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
{true | false}
true
DatabaseMetaData.getColumns method.
false
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
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
OPTIONAL
and
ConnectionRetryCount=1
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
189
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
{true | false}
For DB2 OS/390 and DB2 iSeries, DB2 packages are created in the
collection or library specified by the CollectionId property.
DatabaseName
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
false EXECUTE privileges are granted to the schema that created the
DB2 packages.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
191
Property
Description
InsensitiveResultSetBufferSize
OPTIONAL
{-1 | 0 | x}
-1 The driver caches all insensitive result set data in memory. If the
set data to disk is eliminated, the driver processes the data more
efficiently.
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.
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:
false
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
193
Property
Description
MaxPooledStatements
OPTIONAL
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.
CallableStatements also
The default is 0.
PackageOwner
OPTIONAL
The owner to be used for any DB2 packages that are created.
Password
PortNumber
The TCP port of the primary database server that is listening for
connections to the DB2 database.
OPTIONAL
{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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
195
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.
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}
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.
User
WithHoldCursors
{true | false}
OPTIONAL
true
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
197
Property
Description
AlternateServers
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
DatabaseName
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.
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
Database Comments
Bigint
BIGINT
Blob
BLOB
Char
CHAR
BINARY
Clob
CLOB
Date
DATE
DBClob
CLOB
Decimal
DECIMAL
Double
DOUBLE
Float
FLOAT
Integer
INTEGER
Long Varchar
LONGVARCHAR
LONGVARBINARY
Numeric
NUMERIC
Real
REAL
Rowid
VARBINARY
Smallint
SMALLINT
Time
TIME
Timestamp
TIMESTAMP
Varchar
VARCHAR
VARBINARY
200
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:
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
Property
Description
AlternateServers
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:
retry attempts.
LoadBalancing
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
203
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
204
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Informix
Table 15. Informix Connection Properties (continued)
Property
Description
DBDate
OPTIONAL
Order in which the month, day, and year fields appear in a date string
Y4DM
DMY4
Y4MD
MDY2
Y2DM
MDY4
Y4MD
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
205
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
-1 The driver caches all insensitive result set data in memory. If the
set data to disk is eliminated, the driver processes the data more
efficiently.
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.
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
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
Property
Description
MaxPooledStatements
OPTIONAL
CallableStatements also
The default is 0.
Password
User
208
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Informix
Property
Description
AlternateServers
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
DatabaseName
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
209
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)
210
blob
BLOB
boolean
BIT
byte
LONGVARBINARY
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Informix
Table 17. Informix Data Types (continued)
clob
CLOB
char
CHAR
date
DATE
TIME
DATE
TIMESTAMP
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
Oracle
The following sections describe settings for the Sonic Database Service Oracle driver:
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
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:
retry attempts.
LoadBalancing
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
213
Property
Description
BatchPerformanceWorkaround
{true | false}
OPTIONAL
false
CatalogOptions
{0 | 1 | 2 | 3}
OPTIONAL
and getIndexInfo.
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
215
Property
Description
ConnectionRetryDelay
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
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
true
{-1 | 0 | x}
OPTIONAL
-1
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
217
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:
false Client load balancing is not used and the driver connects to
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
OPTIONAL
CallableStatements also
The default is 0.
Password
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
219
Property
Description
ServerType
{Shared | Dedicated}
OPTIONAL
Dedicated
Unspecified The driver uses the server type set on the server.
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
221
Property
Description
TNSServerName
OPTIONAL
AlternateServers
LoadBalancing
PortNumber
ServerName
ServerType
ServiceName
SID
222
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Oracle
Property
Description
AlternateServers
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
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
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 Database
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
VARCHAR
VARCHAR2
VARCHAR
XMLType
CLOB
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
225
Oracle Database
Oracle10g only
BINARY_FLOAT
REAL
BINARY_DOUBLE
DOUBLE
The following code inserts data into an XMLType column using a prepared statement:
//
226
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
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
Property
Description
AlternateServers
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:
ConnectionRetryCount
retry attempts.
LoadBalancing
228
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Property
Description
AlwaysReportTriggerResults
{true | false}
OPTIONAL
false The driver does not report trigger results if the statement is
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
Property
Description
ConnectionRetryCount
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
230
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
231
Property
Description
InsensitiveResultSetBufferSize
{-1 | 0 | x}
OPTIONAL
-1
232
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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:
false Client load balancing is not used and the driver connects to
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
Property
Description
MaxPooledStatements
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.
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
ProgramName
OPTIONAL
234
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
Cursor
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
235
Property
Description
SendStringParametersAsUnicode
{true | false}
OPTIONAL
false
OPTIONAL
{true | false}
false
236
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
237
Property
Description
AlternateServers
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
DatabaseName
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.
In this example:
238
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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)
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
240
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
241
Sybase
The following sections describe settings for the Sonic Database Service Sybase driver:
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
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:
retry attempts.
LoadBalancing
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
Property
Description
BatchPerformanceWorkaround
{true | false}
OPTIONAL
true
false
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
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
245
Property
Description
ConnectionRetryDelay
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
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
-1
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
247
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:
false Client load balancing is not used and the driver connects to
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
OPTIONAL
CallableStatements also
The default is 0.
Password
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
249
Property
Description
PrepareMethod
OPTIONAL
StoredProc
StoredProcIfParam
Direct
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
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
251
Property
Description
AlternateServers
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
DatabaseName
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.
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
254
Sybase DataBase
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
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
256
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Chapter 10
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:
Scalar Functions
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
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}
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
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
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
LN
WEEK
TYPE_ID
POSSTR
LOG
YEAR
TYPE_NAME
REPEAT
LOG10
TYPE_SCHEMA
REPLACE
MOD
VALUE
RIGHT
POWER
RTRIM
RADIANS
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
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
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
where:
table-reference is
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
Progress OpenEdge
DB2
Informix
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
265
Data Store
Oracle
Sybase
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
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
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
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
268
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
269
270
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Part IV
Part IV explains how to configure and manage BPEL services using the Sonic
Management Console, and contains the following chapters:
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
This chapter describes how to configure BPEL services using the Sonic Management
Console. This chapter contains the following sections:
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
273
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
The Service Maintenance parameters are configured as for any ESB service:
Service Name
Entry Endpoint
Exit Endpoints
Fault 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
Description
BPEL Archive
Staging Directory
276
Persistence
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
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
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
Transient
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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:
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
Embedded Storage This option sets the persistence mode to persistent, using
Oracle:
type=oracle username=username host=localhost port=1521
MySQL:
type=mysql name=dbname username=username host=localhost
port=1521
Important
3.
If you selected Other Database as the data source type, enter the following Database
Options:
Important
280
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
Click OK to set the persistence mode and close the dialog box.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
281
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
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
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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).
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
285
286
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
Chapter 13
This chapter describes how to manage BPEL services. This chapter contains the following
sections:
Terminating Processes
BPEL Profiling
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
287
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
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).
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).
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
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.
time.
290
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
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.
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
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
All Instances
The Started After and Terminated Before fields are disabled when
All Instances is selected.
Live Instances
Terminated Only
Optionally, in the Messages section, click Add to specify the following search criteria
in the table:
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
bpws:getVariableProperty(name,property)
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:
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.
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
293
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
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:
Fault information
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
295
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
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
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
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
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
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
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
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
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