Progress Sonicesb - Configuration And Management Guide jr71

[email protected]

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 [email protected]. 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 ( [email protected]). This product includes software written by Tim Hudson ( [email protected]). Copyright (C) 1995-1998 Eric Young ( [email protected]). 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 [email protected]. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11 12 13 14 15

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

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

20 21 26 33 34 35 37 39 39 40 47

5

Contents

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

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


Contents

Configuring Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Deleting Progress SonicMQ Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

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

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

Part II:

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

Chapter 5: Monitoring and Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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


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

7

Contents

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

Part III:

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

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

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


Contents

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

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

Chapter 10: SQL Escape Sequences for JDBC

257 258 258 265 266

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

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

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


9

Contents

Part IV:

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

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

Chapter 13: Managing BPEL Services

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

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

10

297


Preface

This Preface contains the following sections: ● “About This Guide” describes this manual and its intended audience. ● “Typographical Conventions” describes the text formatting, syntax notation, and flags used in this manual. ● “Progress Sonic ESB Product Family Documentation” describes the books and API online references packaged with the Sonic ESB Product Family. ● “Worldwide Technical ” provides information on how to Progress Software’s customer and evaluation for the Progress Sonic ESB Product Family.


11

Preface

About This Guide This guide is intended for system s. This book is in four parts: ● Part I, “ESB Configuration Tools and Managed Components,” includes the chapters: ■ Chapter 1, “Using Progress Sonic ESB Configuration and Management Tools” introduces Progress Sonic ESB and its configuration and management tools. ■ Chapter 2, “ESB Containers” describes ESB Containers and Activation Daemons. ■ Chapter 3, “ESB Endpoints and Connections” describes how to use ESB components and resources. ■ Chapter 4, “Configuring Web Services” describes using Web Service standards in the configuration and management of ESB components and resources. ● Part II, “Configuring XML Servers,” includes the chapters: ■ Chapter 5, “Monitoring and Logging,” describes Progress Sonic XML Server metrics, notifications, and logging. ■ Chapter 6, “Performance Tuning XML Servers,” includes suggestions to optimize XML Server configuration and application design. ■ Chapter 7, “Backing Up and Restoring Document Collections,” describes how to backup and restore Progress Sonic XML Server document collections. ● Part III, “Configuring Database Services,” includes the chapters: ■ Chapter 8, “Using the Database Service JDBC Drivers,” explains how to configure load balancing, failover, and connection retry for connections made using the drivers. ■ Chapter 9, “Driver Connection Properties and Data Types by Database Brand,” describes the properties and data types for several database brands: Progress OpenEdge, DB2, Informix, Oracle, Microsft SQL Server, and Sybase. ■ Chapter 10, “SQL Escape Sequences for JDBC,” describes the JDBC-defined escape sequences containing standard syntaxes for several language features. ■ Chapter 11, “Configuring SQL Server Windows Authentication,” describes how to use Windows authentication on Microsoft SQL Server with the Progress Sonic Database Service JDBC SQL Server driver. ● Part IV, “Configuring and Managing BPEL Services,” includes the chapters: ■ Chapter 12, “Configuring BPEL Services,” explains how to configure configure BPEL services. ■ Chapter 13, “Managing BPEL Services,” describes how to manage BPEL services. 12


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 interface elements. For example, “From the File menu, choose Open.” ● Bold typeface in this font emphasizes new when they are introduced. ● Monospace typeface indicates text that might appear on a computer screen other than the names of Sonic -interface elements, including: ■ Code examples and code that the must enter ■ System output such as responses and error messages ■ Filenames, pathnames, and software component names, such as method names ● Bold monospace typeface emphasizes text that would otherwise appear in monospace typeface to emphasize some computer input or output in context. ● Monospace typeface in italics or Bold monospace typeface in italics (depending on context) indicates variables or placeholders for values you supply or that might vary from one case to another. This guide uses the following syntax notation conventions: ● Brackets ([ ]) in syntax statements indicate parameters that are optional. ● Braces ({ }) indicate that one (and only one) of the enclosed items is required. A vertical bar (|) separates the alternative selections. ● Ellipses (...) indicate that you can choose one or more of the preceding items. This guide highlights special kinds of information by shading the information area, and indicating the type of alert in the left margin. Note Note indicates information that complements the main text flow. Such information is

especially important for understanding the concept or procedure being discussed. Important Important indicates information that must be acted upon within the given context in order

for the procedure or task (or other) to be successfully completed. Warning Warning indicates information that can cause loss of data or other damage if ignored.


13

Preface

Progress Sonic ESB Product Family Documentation The Sonic ESB Product Family provides the following documentation: ● Introducing the Progress Sonic ESB Product Family — Introduces components of the Sonic ESB Product Family—Sonic 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: Developer’s Guide (Progress Sonic Workbench Online Help) — Provides information about developing, testing, and debugging applications on the Progress Sonic Workbench. Describes the Sonic Workbench, its editors, and tools. Provides information about how to get started with each component of the Sonic ESB Product Family and describes sample applications. ● Progress Sonic ESB Product Family: Configuration and Management Guide — Provides information about configuring and managing components used by the Sonic ESB Product Family. Describes deployment configurations for Sonic ESB, Sonic Database Service, Sonic XML Server, and Sonic BPEL Server ● Progress Sonic ESB Product Family: Deployment Guide — Provides information about moving development projects into test and production environments. Describes recommended build procedures, domain mappings, and reporting features. ● Progress Sonic BPEL Server: Management API Guide — Describes how to use the management API to programatically access BPEL server functionality. ● Sonic ESB API Reference — Online JavaDoc compilation of the Sonic ESB APIs.

14


Worldwide Technical

Worldwide Technical Progress Software’s Sonic staff can provide assistance from the resources on their Web site at www.progress.com/sonic. There you can access technical for licensed Progress Sonic editions to help you resolve technical problems that you encounter when installing or using Sonic SOA products. When ing Technical , please provide the following information: ● The release version number and serial number of SonicMQ that you are using. This information is listed on the license addendum. It is also at the top of the SonicMQ Broker console window and might appear as follows: SonicMQ Continuous Availability Edition [Serial Number nnnnnnn] Release nnn Build Number nnn Protocol nnn ●

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

You can alternatively access version information programmatically for installed Sonic components using the Version class in the Sonic API. See the “Upgrading Sonic ESB Product Family Components” chapter in Progress Sonic ESB Product Family: Installation and Upgrade Guide for instructions.

Note

●

● ● ●

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


15

Preface

16


Part I

ESB Configuration Tools and Managed Components

Part I contains the following chapters: ● Chapter 1, “Using Progress Sonic ESB Configuration and Management Tools” ● Chapter 2, “ESB Containers” ● Chapter 3, “ESB Endpoints and Connections” ● Chapter 4, “Configuring Web Services”


17

18


Chapter 1

Using Progress Sonic ESB Configuration and Management Tools

Chapter 1 describes the tools for configuring and managing the Progress Sonic ESB product family: ● “Overview” describes how and where the Sonic ESB tools are used. ● “Sonic Management Console” introduces this tool for managing and monitoring components deployed in containers, including ESB Containers and Progress SonicMQ brokers. This section also describes the ESB Configured Objects section, used for configuring components such as ESB Containers, endpoints, services, and ESB processes, and deploying them in an ESB Container. ● “ESB 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 Workbench’s 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, Sonic’s 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 a Sonic Workbench in its Directory Service unless explicitly instructed to do so, as you could cause unpredictable behavior in your SonicWorkbench.


19

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

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

Sonic management containers, and brokers istered by one central management node, its Domain Manager. The domain manager is defined by its components: ● A management container that provides caching facilities, communicates with its management node (the broker it hosts), and hosts the other components of the domain manager. ● A broker dedicated to management communications for the domain manager’s two essential functions, the Directory Service and the Agent Manager. ● A Directory Service that provides a centralized point for configuration information, runtime management, and configuration storage. ● An Agent Manager that monitors the state of all management containers in the domain. For information about the domain manager, see the “Introduction to Configuration” chapter in the Progress SonicMQ Configuration and Management Guide and the “Distributing Components” chapter in the Progress SonicMQ Deployment Guide. To use the Sonic ESB configuration and management tools, you must have a domain manager installed and the istration 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 ible, the first step is to start the domain manager. ◆ To start a domain manager: ❖

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

❖

20

On UNIX or Linux, set a console window to the Progress SonicMQ installation directory, and type ./bin/startcontainer.sh and press Return.


Sonic Management Console

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

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

❖

On UNIX or Linux, set a console window to the Progress SonicMQ installation directory, and type ./bin/startmc.sh and press Return. The Sonic Management Console opens. The Create Connection dialog box opens, as shown:

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


21

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools ◆ To connect the Management Console to the domain: 1.

Enter the connection information for the domain: Property

Description

Connection Name

Identity to be associated with this connection.

Domain Name

Name of the domain.

Connection URL(s)

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

Name

The name for connection.

The of the .

For information ing 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:


Sonic Management Console 3.

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

These are the ing 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.


23

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools 4.

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

The containers shown in this figure are: ● DomainManager — The default name of the domain manager’s container makes it easy to recognize. It is highlighted in green, indicating that it is running and all its hosted components are online. ● myHost — The default name of the additional broker in a typical SonicMQ install takes the name of the host system. It is highlighted in red, indicating that it is not running (and therefore its hosted components are offline.) ● Service 1 Container through Service 5 Container — The five management containers used for services installed in this domain are all running and the container that is expanded, Service4 Container, shows that its hosted component Service4 ESB Container is online. ● VerificationContainer — Hosts the service to a container’s setup is offline. See “ing an ESB Container Installation” in the Progress Sonic ESB Product Family: Installation and Upgrade Guide for more information ing this container.

24


Sonic Management Console 5.

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

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


25


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

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

2.

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

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

You should not attempt to manipulate these objects under these circumstances. In the reverse case—the Sonic ESB tools are installed for this SMC, but the connected domain is not Sonic ESB enabled—the 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


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

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

This section can be expanded and contracted by double-clicking ESB Configured Objects. In this example, the section is shown expanded.


27


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

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

28

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


ESB Configured Objects 4.

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

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

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

6.

Choose the Connections tab to see the connections.

7.

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


29


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

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

30

Click on a service in the right 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.


ESB Configured Objects

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

where variable_source_type is one of the following string literals: ■ container — The parameter value is defined in the deployment properties of the ESB container into which the service type is deployed. ■ system — The parameter value is defined in a JVM system property. ■ property — The parameter value from a Java properties file. and source_type_qualifier is the following string literal: ■ dynamic — The parameter value is dynamically extracted from a specified properties file. This qualifier is required if variable_source_type is property and you do not want the property file read from a local cache. and parameter_identifier is one of the following: ■ A valid SonicFS URL indicating a property in a Java properties file — for example: ${property:sonicfs:///workspace/myProject/src/myService.properties#myProp}

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

■


31


Click on Processes, as shown:

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

32


ESB Tool and Commands

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

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

2.

In a default installation, enter the following to connect to the domain manager: connect Domain1 t://localhost:2506

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

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

Each of the ESB Container commands is described in the following section. Note ESB Tool commands are not case sensitive. Many values are case sensistive; for

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


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 session. connect connect domain URL [name ] [managementNode]

Connect to the domain manager at the specified URL. For example: connect Domain1 t://myHost:2506 an aPwd

where: ● ●

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

connect Domain1 “t://myHost:2506,t://myHostBackup:2506” an aPwd ● ●

name are

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

disconnect disconnect

Disconnect from the domain manager. exit bye

exit

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

?

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

34



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

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

For example, to import C:\PO.xml to /Resources in SonicFS: ESB> add file PO.xml C:\PO.xml Adding file into Directory Service... name = PO.xml file = C:\PO.xml override = false

add directory add directory sonicfs_directory source_directory

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


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

Delete the specified directory from domain Also deletes all subdirectories and files in those directories. export file export file name filename

Export a file from the domain to the specified file and path. The export command is ed for all file types and s 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



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

list list [type]

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

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

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

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


37


dump dump [type] [name] [filename]

Dump is an advanced command. You might be requested to use a specified dump syntax by Sonic technical . 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 s 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


License Container Commands

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

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

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

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

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

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


39


container status container status container_name

Reports the status of a management container. For example: ESB> container status DomainManager Container Name = DomainManager, State = Online, Container Config Name = /Containers/DomainManager, Host = NBSRUSSO3.bedford.progress.com Component Name = ActivationDaemon1, State = Online Component Name = Broker1, State = Online

container [suspend | resume | reload] container [suspend|resume|reload] container_name component_name

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

Deployment Tool Commands Deployment tool commands are in the following categories: ● Analysis for deployment ● Exporting for deployment ● Tailoring archives for import ● Importing or merging for deployment

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

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

40



The general syntax of the analysis commands is: ● Uses one or more storeType, each with storeParams as follows: ■ The first -storeType storeParams identifies the source artifact store, and the next -storeType storeParams identifies the target artifact store. ■ storeType is { xar | fs | ds }. ■ storeParams are: ❑ When storeType is xar, the archive location on a file system ❑ When storeType is fs, the root of the hierarchy on a file system ❑ When storeType is ds, the management connection to a domain in the form: domain url [name ] [managementNode] ●

●

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

Default Output File

diff

Sonic_Diff.xml

mqdepends

Sonic_Dependency.xml

mqrevdepends

Sonic_ReverseDependency.xml

impact

Sonic_ImpactAnalysis.xml

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


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 ESB diff only assesses specific filetypes in certain store types. The stores can be Sonic archive files—XAR 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 a a

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

where the optional parameters include: ● artifact1 artifact2 ...(a series of specific files in the store to analyze) ● artifactListFile (a text file that provides a list of files in the store to analyze) The mqdepends command assesses a source artifact store to evaluate and report on the dependencies of ESB artifacts on SonicMQ configuration objects. You can use this information to create or the existence of the specified dependencies in a target Directory Service store. The stores can be a Sonic archive file, file system, or a Directory Service store. Sonic ESB dependencies on SonicMQ artifacts include: ● Endpoints for their destination dependencies (topics, queues, or routing). ● ESB connections for SonicMQ connection parameters (and, therefore, the broker location and port where static destinations must be created. As an example, to produce a dependency report on specified files: mqdepends -fs C:/myinstalldir/ESB -include processA serviceA serviceB

42



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

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

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

Assessing impact on a Directory Service store requires a connect command to establish a connection to the domain prior to invoking impact. An impact analysis report combines features of diff and mqdepends. Together, these features define the impact on the target store that would result from merging the source store into the target store. Because this report assesses impact, the following information is also included: ● If a binary file type is different, the impact analysis report indicates that the file in the source store will overwrite the one in the target store. ● If a file exists in the source store but not in the target store, the impact analysis report indicates that a new file will be added to the target store. However, if a file exists in the target store but not in the source store, it is not reported as it is not impacted and will not be affected by any import actions. ● If a dependency indicates that SonicMQ configuration objects must be created, the impact analysis report describes the requirement. Conversely, if existing SonicMQ configuration objects are no longer required, the impact analysis report notes that fact. As an example, to report on the impact of an archive on a Directory Service store: impact -xar sourceStore.xar -ds Domain1 myHost:2506 a aPwd


43


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

Export to a file system path as a file structure. export archive export archive targetArchiveFile [sourceArchiveFile | exportPropFile | all]

Export to a Sonic archive file. export bootfile export bootfile container_config_name [filename]

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

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

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

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

44



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

Import into a domain from a file system path as a file structure where: ● sourceFileSysPath is the root of the file system hierarchy that contains the files to be imported into the connected Directory Service’s store. ● One of the following arguments is used: ■ importPropFile — When an import properties file was created and saved, it can be applied as a parameter of the command to apply the defined overwrite and ignore settings. ■ override — Set overwrite of matching files to true. import archive import archive sourceArchiveFile [importPropFile | override]

Import into a domain from a Sonic Archive file.


45


merge (standard form) merge -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]

where: ● The first -storeType storeParams identifies the source artifact store, and the next -storeType storeParams identifies the target artifact store. ● storeType is { xar | fs | ds }. ● storeParams are: ■ When storeType is xar, the archive location on a file system ■ When storeType is fs, the root of the hierarchy on a file system ■ When storeType is ds, the management connection to a domain in the form: domain url [name ] [managementNode] ●

●

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

For example, to merge an archive into a Directory Service store: merge -xar sourceStore.xar -ds Domain1 myHost:2506 a aPwd -out c:\out.xml

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

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

46


Shutting Down Sonic Components and Sonic ESB Tools

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

In each domain, shut down any running containers: 1.

In the Sonic Management Console, select the Manage tab.

2.

Choose the containers folders, typically /Containers

3.

Right-click on each container name you want to stop, and select Operations > Shutdown.

4.

Be sure to shut down the container named DomainManager last.

The specified configuration objects are stopped. ◆ To shut down Sonic ESB tools: 1.

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

2.

If the JMS Test Client is running, close it.

3.

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

4.

In the Sonic Management Console, select Action > Exit.

The Sonic ESB tools are stopped.


47


48


Chapter 2

ESB Containers

Progress Sonic ESB is a framework composed of classes and APIs for architecting, developing, and configuring distributed services. This framework includes an ESB Container, a centralized configuration service, and key routing and processing services. This chapter explains how to work with Sonic ESB Containers and describes services and messages in the Sonic ESB framework. This chapter contains the following sections: ● “Overview” ● “Creating ESB Containers” ● “Managing the Services Associated with an ESB Container” ● “Deploying an ESB Container in a Management Container” ● “Changing the State of Management and ESB Containers” ● “Monitoring Service Metrics and Notifications” ● “Enabling Integration with Actional™ for Visualization” ● “Logging and Tracing” ● “Using Activation Daemons” Note The tasks in this chapter are oriented toward deployment specialists. Sonic ESB Product

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


49

Chapter 2: ESB Containers

Overview ESB Containers host services, endpoints, and ESB processes. Configuration information is provided to an ESB Container from a centralized Directory Service. The Directory Service notifies containers of configuration changes and updates each container’s cache of configuration information. An ESB Container also provides access to a common log file for all the services it hosts. In addition to ESB processes, services, and endpoints, ESB Container components include: ● Management framework access — Provides access to the centralized configuration store and standard facilities for managing the container’s assets. ● Connectivity components — Manage connections and communication with external resources, including JMS. They include the endpoint manager for access to existing endpoints (by name) or creation of new ones. ● Services and ESB processes — Handle the application-level components or services and manage the interaction of service code with the environment, including the application manager (which controls the lifecycle of ESB services,) the service application (which sets up each instance of a service) and the dispatcher (which es each message to a service and sends processed messages to the next destination or endpoint.) ● Factory objects — Create instances of objects that services require: ■ MessageFactory — Creates new messages to be sent. ■ EnvelopeFactory — Creates new envelopes to associate messages with addresses. ■ AddressFactory — Creates addresses for envelopes allowing messages to be sent to an ESB process, service, or endpoint. An ESB Container manages the lifecycle of services and creates a pool of connections to JMS endpoints (destinations). Each ESB Container within a Sonic domain must have a unique name.

50


Overview

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

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

2.

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

3.

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

4.

The configuration of the ESB Container is requested.

5.

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

6.

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

7.

During startup, the ESB Container might make additional JMS connections required by the services it s. These connections are independent of the initial management connection. Typically, the names and s for these application connections are different from the name and used for management connections.

A running ESB Container continues to make management requests on its own and responds to istrative requests from the management tools, such as the Sonic Management Console. Some reasons for this additional communication include: ● Additional configuration information is needed by a service. These requests are directed to the Directory Service, (for example, process configurations.) ● Management tools send life cycle management commands to the management container, for example, to suspend operation, reload configuration information, or initiate a shutdown operation. ● Requests for status from other components or tools.


51


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

The ESB Container reads configuration information from the Directory Service.

2.

The ESB Container establishes JMS connections to Progress SonicMQ destinations (topics or queues).

3.

The ESB Container pools JMS connections.

4.

Messages arriving on their Progress SonicMQ destinations are allocated to services that implement the XQService interface by calling their service( ) method, using the predefined Quality of Service (QoS)—EXACTLY_ONCE, AT_LEAST_ONCE, or BEST_EFFORT.

5.

Messages are processed by the services.

6.

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

7.

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

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

52


Creating ESB Containers

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

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

2.

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


53

Chapter 2: ESB Containers 3.

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

Description

Name

The name of the ESB container.

Intra-container Messaging

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

ESB (JMS) Connection

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

HTTP Routing Connection

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

For more information, see the Progress Sonic ESB Product Family Developer’s Guide in the

Eclipse help. 4.

In the Actional Integration section, specify the following properties: Property

Description

Enable Actional Instrumentation

Select this option to enable Actional Server visualization on this ESB container. By default, the option is not selected (unchecked). See the chapter on “Instrumenting Sonic ESB” in the Actional Interceptor Guide.

Enable Payload Capture

When Actional instrumentation is enabled, declares whether the instrumentation should include the message body.

The Actional Integration feature requires Progress Actional software products to provide visibility, control, and enforcement of deployed assets. See their Web site at www.progress.com/actional. 5.

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

You now need to add services to the ESB Container.

54


Creating ESB Containers ◆ To add services to an ESB Container: 1.

In the left 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 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 of the Sonic Management Console to apply the changes to your ESB Container. The service or ESB process you selected appears in the right . 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.)


55


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

56


Creating ESB Containers

Viewing or Editing ESB Container Properties Follow this procedure to view and edit the properties of installed ESB Containers. ◆ To view or edit the properties of installed ESB Containers: 1.

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

2.

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

In this example, the ESB Container VerificationContainer is selected so its properties are displayed.You can edit the properties for the selected container (except its name), as described in “Creating ESB Containers” on page 53.


57


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

In the left in the Sonic Management Console, under the ESB Configured Objects node, expand the ESB Containers folder and select an ESB Container. The right 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:


Managing the Services Associated with an ESB Container

Adding Services or ESB Process Entry Points to an ESB Container Follow this procedure to add a service or ESB process entry point to an ESB Container. ◆ To add a service or ESB process entry point to an ESB Container: 1.

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

2.

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

Show Services Show Processes

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

3.

a.

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

b.

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

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.


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

to implement the changes.

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

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

2.

Select the service and click Delete.

3.

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

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

restarted to implement the changes.

60


Deploying an ESB Container in a Management Container

Changing the Number of Listeners on Services in ESB Containers You can edit a service to change the number of listeners. Each listener is a thread. ◆ To edit the number of listeners on a service associated with an ESB Container: 1.

In the left 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 , select a service whose listeners you want to edit.

3.

Change the number of listeners to the value you prefer.

4.

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

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

restarted to implement the changes.

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

Section

Creating a management container

“Configuring Containers”

Adding an ESB Container as a component in a management container

“Configuring Container Components”

Generating a management container boot file

“Generating Container Boot Files”

Using fault tolerant (backup) management containers

“Generating Containers”

(Also see the SonicMQ Deployment Guide chapter “Fault Tolerant Application Containers.”) Note that there is no configuration for a fault tolerant ESB Container.


61


Setting Test Mode for ESB Containers Used in Development To use a new ESB Container, the Sonic Workbench requires that you set the ESB Container’s property TEST_CONTAINER_MODE to true. ◆ To set an ESB Container to Test Mode:

62

1.

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

2.

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

3.

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

4.

Choose the Deployment Parameters tab, and then click Add.

5.

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

6.

The deployment parameter appears as shown:

7.

Click OK to apply the setting.


Deploying an ESB Container in a Management Container

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

In the Sonic Management Console’s 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.


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.

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

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

the service type.

64


Changing the State of Management and ESB Containers

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

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

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


65


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

Description

Launch

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

Restart

Restarts the container

Shutdown

Shuts down the container

Reset Metrics

Resets container-wide metrics

Invoke Diagnostics...

Opens the Sonic Diagnostics dialog box.

For more information on management container operations, see the “Managing Containers and Collections” chapter in the Progress SonicMQ Configuration and Management Guide. Warning Do not include an external jndi.properties file in the classpath of an ESB Container (or

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

66


Changing the State of Management and ESB Containers 3.

4.

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

Description

View

Views the contents of the container log.

Clear

Clear the contents of the container log.

Save to File...

Saves the container log to a file.

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

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

67


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

Description

Start

Starts the ESB Container

Stop

Stops the ESB Container

Reload

Unloads the ESB Container, reloads configuration information, and restarts services in the ESB Container

Abort

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

Clear Error

Clears the last error.

Reset Metrics

Resets container-wide metrics.

For more information on component operations (ESB Containers are components in management containers), see the “Managing Containers and Collections” chapter in the Progress SonicMQ Configuration and Management Guide and the Contaniers view in the Sonic Workbench. 6.

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

Description

Start

Starts the ESB service.

Stop

Stops the ESB service.

Abort

Aborts the ESB service.

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

68


Monitoring Service Metrics and Notifications

Monitoring Service Metrics and Notifications All ESB services deployed in an ESB container standard metrics and notifications.

Standard Metrics All ESB services deployed in an ESB container the following metrics: ● esb.service.messages.Received — Records the number of message envelopes received—that is, the number of times service has been invoked on the service instance. This metric includes any messages received intracontainer, through dynamically ed entry endpoints, and so on. ● esb.service.messages.ReceivedIntraContainer — Records the number of message envelopes received intracontainer. ● esb.service.messages.ReceivedPerSecond — Records the rate per second at which this service has been invoked over the collection interval. ● esb.service.messages.ReceivedPerMinute — Records the rate per minute at which this service has been invoked over the collection interval. ● esb.service.messages.ReceivedPerHour — Records the rate per hour at which this service has been invoked over the collection interval. ● esb.service.messages.Rejected — Records the number of message envelopes that were rejected by the service instance.


69

Chapter 2: ESB Containers ●

●

●

●

●

esb.service.messages.Faulted —

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

◆ To enable a service metric:

70

1.

Open the Sonic Management Console and select the Manage tab.

2.

Select a running ESB Container.

3.

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


Monitoring Service Metrics and Notifications 4.

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

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

Standard Notifications Notifications are associated with the delivery of event information. The ESB Container s 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 ed: ● Service started successfully ● Service failed to start ● Service stopped successfully ● Service failed to stop ● Service aborted


71

Chapter 2: ESB Containers ◆ To monitor notifications: 1.


2.

Select a running ESB Container, right-click on the container, and select Notifications... . The Monitoring dialog box opens with its Notifications tab:

3.

You can select one or more notifications, and for each notification, select Watch and select whether to watch: ■ By Component (ESB Container) ■ By Container (management container) ■

By Domain

The Sonic Management Console marks notifications that are being watched:

The Sonic Management Console opens a Notification Watcher.

72


Enabling Integration with Actional™ for Visualization

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

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


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 container’s properties with the Variable name com.actional.lg.interceptor.config and, for the Value, the complete path, such as usr1/a/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 istration 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


Logging and Tracing

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

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

2.

Right-click on the ESB Container and select Properties.

3.

The identity and status of the ESB Container is displayed:


75


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

These settings include: ■

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

■

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

■

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

■

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

usage ■

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

example, lifecycle events 5.

Click OK to apply the settings.

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

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

76


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

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

2.

In the right , 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.


77


Using Activation Daemons Using an Activation Daemon is a way to launch new containers as spawned processes of the container hosting the Activation Daemon. This allows new containers to be launched by remote istrative clients without the having to log on to that host. A typical use would be to have the container hosting the Activation Daemon launched as a Windows service on Windows platforms or a startup process under UNIX. An Activation Daemon monitors the health of its spawned containers and, depending on configured rules, restarts those containers upon failure. Normally, one Activation Daemon is deployed per host. Multiple Activation Daemons can be created per domain. Containers can be launched by the Activation Daemon: ● At Activation Daemon startup time ● At a configured time ● After a container failure (up to a configurable number of retries) ● On demand from the Sonic Management Console or through the Activation Daemon’s management API (see the “Using the Runtime API for the Sonic Management Environment” chapter in the Progress SonicMQ istrative Programming Guide) This section demonstrates how to create and configure an Activation Daemon to start an ESB Container. As an example, the procedures describe how to create an Activation Daemon to automatically start the Service5 container when the Activation Daemon’s container starts. See the “Configuring Framework Components” chapter in the Progress SonicMQ Configuration and Management Guide for detailed information on using Activation Daemons. The steps required to create, configure, and test the Activation Daemon are:

78

1.

“Creating an Activation Daemon” on page 79

2.

“Adding an Activation Daemon to a Management Container” on page 79

3.

“Adding an ESB Container to an Activation Daemon’s Activation List” on page 81


Using Activation Daemons

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

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

2.

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

3.

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

4.

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

5.

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

6.

Click OK.

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


79

Chapter 2: ESB Containers ◆ To add an activation daemon to a management container: 1.

In the Sonic Management Console’s 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 name and for management communications in the domain.

3.

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

Description

Name

The name of the component you want to add to the container. For this example, enter AD_for_Services.

Component

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

Auto Start

Specifies whether to automatically start the component when the hosting container starts. For this example, check Auto Start.

Tracing Mask

Enter the tracing mask integer for this component.

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

4.

80

Click OK to add the component to the container.



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

In the Sonic Management Console’s Configure tab, navigate to the Activation Daemon you created, then right-click on it.

2.

Choose Add Container to Activation List.

3.

Under the General tab, specify the following properties: Property

Description

Container

Name of the container to associate with the Activation Daemon. For this example, select ... then select Containers\Service5 Container and click OK.

Number of Retries

Number of times the ESB ContainerActivation Daemon should attempt to restart the spawned container. For this example, use the value 4 instead of the default value, 0.

Retry Interval

Number of seconds between attempts by the Activation Daemon to restart the spawned container. For this example, use the value 15 instead of the default value, 0.

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


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.

Note Setting JVM System Properties on a Management Container

You can maintainthe JVM system properties for a management container that is on an Activation Daemon’s activation list by using the Sonic Management Console to open the management container’s 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


Chapter 3

ESB Endpoints and Connections

This chapter first references to endpoints and ESB addresses, and then shows how they are configured. Then connections are presented and shows how they are configured. The chapter contains the following sections: ● “Overview” ● “ESB Addresses and References to Endpoints” ● “Evaluating Endpoint Requirements on JMS Destinations” ● “Configuring Progress SonicMQ Endpoints” ● “Fault Tolerant Connections and Reconnection” ● “Every endpoint has an associated connection. The following procedure describes how to view existing connections and configure a new connection.” Note In the development environment, the Sonic Workbench handles the creation of endpoints

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


83

Chapter 3: ESB Endpoints and Connections

Overview ESB endpoints and connections enable communication among services. Endpoints are destinations where ESB services send and receive messages. The definition of an endpoint includes its connection, the URL address where the destination resides. An application accesses a service by sending a request to the service’s entry endpoint. Progress Sonic ESB endpoints include Java Messaging Service (JMS) destinations— queues and topics—that are accessed through connections to SonicMQ messaging brokers. Endpoints provide queuing and persistence between services. This persistence allows an ESB process to be fault-tolerant and provides an overall Quality of Service (QoS) that can guarantee processing in case of provider failure. Endpoints are defined by three sets of properties: ● Name — A globally unique name for accessing the endpoint ● Connection — The logical connection that instantiates the endpoint ● Parameters — The specific parameters within the logical connection that distinguish the endpoint (for example, the name of a Progress SonicMQ queue or topic) The following view of an endpoint in the ESB Configured Objectssection of the Sonic Management Console shows some of the properties:

84


ESB Addresses and References to Endpoints

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

creates listeners for a service Inbox, or when it delivers messages from the Outbox. However, as a service developer, you can also send messages directly to an endpoint from inside a service: ● To send messages as the output of the service, you simply place the message in the service’s Outbox with the appropriate address. ● To send messages synchronously (to wait for a reply on a temporary JMSReplyTo destination), use the call( ) method on the endpoint. ● To send messages asynchronously, use the XQDispatch.

ESB Addresses and References to Endpoints When ESB services and ESB processes are configured, they are associated with an endpoint that is used to receive messages (the entry endpoint). When messages are delivered to a service (by the dispatcher), the message is placed in an envelope with an address. An address is a generic term for ESB processes, services, or endpoints that can serve as destinations for a service or process exit, fault, or regular message endpoint. There is also a special REPLY_TO address for services configured as Request/Reply. If the message sender is a service, the address is interpreted as an endpoint. Messages can be sent directly to a ESB process or service (as well as to the endpoint itself). ESB addresses include: ● Endpoints — A specific destination on a defined connection. ● ESB processes — Specifies binding to defined endpoints in their definition. That endpoint is used in their first step (bying the entry endpoint) ● Services — Specifies binding to a defined entry endpoint of the service, or the service itself when intra-container messaging is in use. When you define a service or ESB process or adapt a service or ESB process to a target domain, you specify four categories of ESB addresses: entry, exit, fault, and rejected message. The following sections discuss each of these categories.


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


ESB Addresses and References to Endpoints

Rejected Message Endpoint The rejected message endpoint (RME) can be any valid XQAddress object including, an endpoint, a service, and an ESB process. It handles messages that are an invalid type for the process, messages that throw exceptions in the service() method of the service, and messages that failed to send to their Fault or Outbox addresses. Messages that cannot be processed are sent to the RME in the event of processing failures. This provides a similar function to the SonicMQ Dead Message Queue (DMQ). Every service can have an RME. Messages that cannot be processed are always sent to the RME in the event of processing failures. The messages are sent to the RME by the services framework, not directly by the services. The RME handles: ● Messages that throw exceptions in the service( ) method of the service ● Messages that were in the services Fault box or Outbox, but which could not be delivered (for example, the queue underlying the ESB endpoint does not exist.) When a message is sent to a rejected message endpoint, it is sent as a multipart message. The first part provides information about the rejected message, and the balance of the messages is the original message. If the original rejected message was itself a multipart message, the first part is the information section and the other parts follow it in the same sequence as the original message parts. The first part is a text/xml message with three sections: ● rejectedCode — A String identifier pointing to the reason for rejection (a list of rejected codes is available in com.sonicsw.xq.ErrorCodes) ● rejectedLocation — The location of the failure; it can have these optional attributes: ■ locationName —The name of the computer where the rejection occurred ■ containerName — The name of the ESB Container that rejected the message ■ serviceName — The name of the service that rejected the message ■ processName — The name of the ESB process that was performing the action ■ stepName — The name of the process step at which the message was rejected ● rejectedString — Details of the failure, including a stack trace of the failure or exceptions causing the rejected message


87


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

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

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

An error outside the service( sent to the RME.

)

method, delivering Inbox or Outbox messages, is also

The following scenarios result in rejected message processing: ● If the address on an XQMessage in the Outbox or Fault box is invalid or empty: rejectedCode = SEND_NULL_ADDRESS ●

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

) method:

rejectedCode = XQ_ENDPOINT_EXCEPTION ●

If some other error occurs in the dispatcher processing the message: rejectedCode = MESSAGE_SEND_FAILURE

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

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

88


Evaluating Endpoint Requirements on JMS Destinations

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

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

●

What quality of service (QoS) is required? ■

●

For EXACTLY_ONCE or AT_LEAST_ONCE QoS, messages can be sent PERSISTENT, and topic subscribers should be durable. See “Using Concurrent Durable Subscriptions to Topics” on page 91.

Are the destinations queues or topics? ■

■

●

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

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

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

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

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

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


89


Table 1 maps the destination configurations to destination requirements. Table 1. Mapping Destination Requirements

QoS

Destination Type Multiple Services

Single Service Instances

AT_LEAST_ONCE

Topic

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

●

●

or ●

EXACTLY_ONCE

● ●

BEST_EFFORT

● ● ●

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

Queue

●

No additional configuration required

●


Topic

●

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

●

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


●

● ● ●

Queue

●

● ● ●


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



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

Using Concurrent Durable Subscriptions to Topics You can configure the entry endpoint of a service to define a durable subscription to a topic. In Sonic ESB, multiple service instances can concurrently process messages sent to a durable subscription. Durable subscriptions are created using a unique prefix appended to the subscription name configured on the JMS endpoint. The unique prefix consists of the management container name, the name of the ESB service configuration (the service name), and the ID of the message listener. The Concurrent Durable Subscription setting on an endpoint is a boolean value: ● When set to False, the number of listeners to is limited to one. Also, only one instance of the service can be running anywhere in your ESB. This setting is preferred if you care about guaranteeing order in processing. The effect is similar to setting Exclusive on a queue. ● When set to True, the default value, multiple containers are allowed to run the service, and each of those containers can have multiple listeners. This setting is appropriate when you want to load-balance and scale processing, and are not concerned about order in processing. Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

91


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 ESB’s naming convention for this feature: ● A service named Service1 is deployed in MFContainer1 and MFContainer2. Service1 has: ■ Two listeners in MFContainer1 ■ One listener in MFContainer2 ● The subscription name is myDurableSub ● The topic that is subscribed to myDurableSub is T1 ● These services share a subscription to the topic name [[Service1]]T1 (concurrent durable subscriptions in Sonic ESB have shared subscriptions enabled by default) ● The dynamically generated subscription names are: ■

MFContainer1:Service1:1:myDurableSub

■


■


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



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

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


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 non-clustered queues

Use normal or shared topics

One cluster, multiple brokers

Use clustered queues

Use normal or shared topics

Multiple nodes with some nodes as clusters, some as brokers

Use global, clustered queues

Use either:

Use node-qualified entry endpoint names, for example, Node::aQueue

●

Node-qualified entry endpoint names, for example, Node::aTopic (shared subscriptions are not allowed)

●

GSA and no overlapping topic names

When choosing JMS destinations for queues, consider the following: ● For clustered brokers, you should use clustered queues ● For multiple nodes, you should use global queues and entry endpoints that are qualified by the node name When choosing JMS destinations for topics, consider the following: ● All topics are clustered and global ● For multiple nodes, either use node-qualified names for the entry endpoint or use global subscription architecture (GSA) and global subscription nodes. (For information on GSA, see the “Multiple Nodes and Dynamic Routing” chapter in the Progress SonicMQ Deployment Guide.

94


Configuring Progress SonicMQ Endpoints

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

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

2.

Select an endpoint from the list. The ESB Configured Objects section of the Sonic Management Console displays the properties of the selected endpoint, as shown:


95

Chapter 3: ESB Endpoints and Connections 3.

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

4.

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

Property

Description

Endpoint Name

A unique name.

Connection

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

Quality of Service

Select one: ●

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

●

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

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

WSDL URL

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

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

JMS Destination Type

96

Select Queue or Topic.


Configuring Progress SonicMQ Endpoints

Property

Description

Destination Name

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

Message Selector

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

Concurrent Durable Subscription

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

Durable Subscription Name

Name of the Progress SonicMQ durable subscription. See “Using Concurrent Durable Subscriptions to Topics” on page 91 for information about durable subscription names.

Priority

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


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 0 retains the message indefinitely.

●

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

●

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

Message Prefetch Count

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

Message Prefetch Threshold

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

Shared Subscriptions

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

Flow To Disk

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

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

Send Timeout

USE_BROKER_SETTING — No setting on the endpoint (the broker setting for this feature is used). The default setting is USE_BROKER_SETTING.

●

ON — All messages to this endpoint will flow to disk.

●

OFF — No messages to this endpoint will flow to disk.

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

98

●

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


Fault Tolerant Connections and Reconnection

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

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

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

2.

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

3.

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

Fault Tolerant Connections and Reconnection Progress Sonic ESB provides fault tolerant client connections that allow ESB services to become failure resistant when used in a replicated broker environment. Enabling fault tolerant connections allows your ESB services to recover connections without message loss or duplication in the following circumstances: ● Reconnect to the same broker if the connection is lost due to network failure ● Reconnect to the same broker through redundant network interfaces if the connection in lost due to network failure ● Reconnect to a broker that is configured as a backup broker if the primary broker fails ● Reconnect to a broker that crashes and recovers from the log if that broker is configured with full broker crash recovery The fault tolerant and reconnect properties you can set for a connection are: Connection Parameter

Sonic Management Console Property

Default Value

faultTolerant

Enable Fault Tolerant Connection

False

initialConnectTimeout

Initial Connect Timeout

30 seconds

faultTolerantReconnectTimeout

Fault Tolerant Reconnect Timeout

60 seconds


99


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

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

100


Fault Tolerant Connections and Reconnection

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

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

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

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


101


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

Quality of Service In the case of an interrupted connection, the ESB reconnect creates a new connection and the connection state is lost. (In a fault tolerant connection, the state is preserved and the connection never appears interrupted). This behavior has the following impact on QoS: ● Best Effort — Messages may be lost, no Fault or RME message is guaranteed. ● At Least Once — If the connection is lost before a message is acknowledged, the acknowledgement fails, but messages already sent to the Outbox and Fault box are still processed. A copy of an incoming message that is not acknowledged is sent to the RME. The unacknowledged message is redelivered to the service (for queues), or to the durable subscription endpoints (for topics). ● Exactly Once — If the connection is lost while a message is being processed, a copy of incoming message is sent to the RME. The message is redelivered to the service (for queues), or to the durable subscription endpoints (for topics). Messages sent to the Outbox and Fault box are not processed in this case.

102


Configuring Connections

Setting the Ping Interval You can enable or disable sending active pings on a connection by setting the pingInterval connection property. When used where messages are sent to the endpoint at a low frequency, the ping can detect a connection drop and trigger reconnect logic to keep the connection alive. However, when large messages are sent on a slow network, a small ping interval can cause a response failure that can be interpreted as a connection drop. Consider the size and frequency of messages that will be sent to the endpoint when setting this property: ● For non-fault tolerant connections, the default pingInterval value is 90 seconds. ● For fault tolerant connections, the default pingInterval value is 30 seconds. Ping interval behavior for fault tolerant connections differs from that of non-fault tolerant connections in that the ping does not require a response from the broker in fault tolerant connections. A lack of response from the broker does not result in a connection failure in this case.

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

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

2.

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


103


104

3.

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

4.

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


Configuring Connections 5.

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

Description

Connection Name

A unique, meaningful name.

Connection Type

Accept the required value, Progress SonicMQ Connection.

Connection URLs

One or a comma-delimited list of URLs for the Progress SonicMQ brokers to make connections are made (in the format [protocol://]hostname[:port]).

Name

The name to authenticate with the Progress SonicMQ broker.

The to authenticate with the Progress SonicMQ broker.

SPI Classname

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


105


Set the maximum sessions for this connection: Property

Description

Maximum Receive Sessions Per Connection

When configuring a connection, you specify the number of sessions Progress Sonic ESB creates on an underlying Progress SonicMQ connection for Progress Sonic ESB entry endpoints: ●

Unlimited — The default for a single connection configuration.

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

Single — Progress Sonic ESB creates a dedicated Progress

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

Important

106

Maximum BEST_EFFORT Sessions

The size of the pool of Progress SonicMQ sessions created for sending messages at a BEST_EFFORT QoS level. This number should grow as the number of listeners grows. Specify a numeric value. The default is 3.

Maximum AT_LEAST_ONCE Sessions

The size of the pool of Progress SonicMQ sessions created for sending messages at an AT_LEAST_ONCE QoS level. This number should grow as the number of listeners grows. Specify a numeric value. The default is 3.

Maximum EXACTLY_ONCE Sessions

The size of the pool of Progress SonicMQ sessions created for sending messages at an EXACTLY_ONCE QoS level. This number should grow as the number of listeners grows. Specify a numeric value. The default is 3.

Maximum Web Service Sessions

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

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


Configuring Connections 7.

Set the ping interval and fault tolerant connection parameters: Property

Description

Ping Interval

The interval in seconds for sending active pings on the connection. Specify a numeric value: ●

The default for non-fault tolerant connections is 90.

●

The default for fault tolerant connections is 30.

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

Specifies whether to enable fault tolerant connections for the endpoint. This setting is optional, either True or False; the default is False. See “Fault Tolerant Connections and Reconnection” on page 99 for more information.

Initial Connect Timeout

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

Fault Tolerant Reconnect Timeout

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

JMS Connection ID

When a JMS Connection ID is entered ( a non-empty string), fault tolerant clients can reconnect to a broker before the broker’s pending reconnect timeout is reached. However, taking advantage of this functionality will not allow multiple, simultaneous JMS connections using use the same JMS connection ID. See “Fault Tolerant Connections and Reconnection” on page 99 for more information.


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

Specifies the location of the Certificate Authority (CA) certificate used to connect to the Progress SonicMQ broker.

SSL Certificate Chain File

Specifies the pathname that points to the file containing the Progress SonicMQ broker certificate chain for SSL.

SSL Private Key File

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

SSL Private Key

Provides the to encrypt the broker private key for SSL.

SSL Certificate Chain Form

Specifies the format of the file containing the broker certificate chain: ●

PKCS7

●

PKCS12

●

LIST

SSL Cipher Suites

The value is a comma-delimited list of all cipher suites, in priority order, ed by the Progress SonicMQ broker connection. For broker-client communications the broker that initiates the connection negotiates to the highest-priority cipher suite they both . The default is SSL_RSA_WITH_3DES_EDE_CBC_SHA.

SSL Provider Class

Specifies the Progress SonicMQ adapter class name of the SSL implementation. The ed adapters are: ●

progress.message.net.ssl.jsafe.jsafeSSLImpl

(the default) ●

Note

108

progress.message.net.ssl.jsse.JSSEImpl

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


Deleting Progress SonicMQ Connections 9.

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

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

In the left 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 , click the Connections tab. The Sonic Management Console lists the available connections under the Connections tab.

3.

Select a connection and click Delete.

4.

Confirm the selection. Progress Sonic ESB deletes the connection.


109


110


Chapter 4

Configuring Web Services

This chapter describes how to configure Web Services using WS-* standards in the following sections: ● “Overview” ● “Configuring WebService Protocols for ESB Processes” ● “Related Configuration Documentation”


111

Chapter 4: Configuring Web Services

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

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

112


Related Configuration Documentation

An endpoint URL is used by SOAP/HTTP clients to access a web service implemented by an ESB process. A URL extension can be mapped to a JMS destination or a URL. If it is mapped to a URL, the URL must be either a JNDI URL or a sonic URL of the form: sonic:///node_name/process_name

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

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

Configurable Element

Location

HTTP Direct Acceptor Web Service Protocol

See the “Configuring Acceptors” chapter of the Progress SonicMQ Configuration and Management Guide.

HTTP Web Service Protocol Routing

See the “Configuring Routings” chapter of the Progress SonicMQ Configuration and Management Guide.

Broker

See the “Configuring SonicMQ Brokers” chapter of the Progress SonicMQ Configuration and Management Guide.


113

Chapter 4: Configuring Web Services

114


Part II

Configuring XML Servers

Part II contains the following chapters: ● Chapter 5, “Monitoring and Logging” ● Chapter 6, “Performance Tuning XML Servers” ● Chapter 7, “Backing Up and Restoring Document Collections”


115

116


Chapter 5

Monitoring and Logging

Chapter 5 includes the following sections: ● “Monitoring” describes Sonic XML Server metrics and notifications. ● “Logging” describes service-specific information and Sonic XML Server-related information, including method parameters, inputs, and outputs, and transaction logs.


117

Chapter 5: Monitoring and Logging

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

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

●

■

ArchivedPerMinute

■

GetsPerMinute

■

(both from the document collections and the Inbox) PutsPerMinute (both to the document collections and the Outbox)

■

RemovesPerMinute

Messages: ■

●

Processing actions: ■ ■

118

Processed TranslationsPerMinute XQueriesPerMinute


Monitoring

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


2.

Select a running ESB Container containing an XML Service instance.

3.

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

4.

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


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:

For information on watching and disabling metrics, as well as general information on metrics, see the “Monitoring” chapter in the Progress SonicMQ Configuration and Management Guide.

120


Monitoring

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

xmlService.invalidArchiveAddress

Notifications from the management container’s components include: ● ●

system.state.Offline system.state.Online

The xmlService.invalidArchiveAddress notification is published when a document collection’s archive address is invalid at runtime. Its attributes are: ● serviceName — Name of the XML Service that performed the operation ● documentCollectionName — Name of the collection on which the operation was performed ● documentName — Name of the document being archived when the failure occurred ● message — Message giving further details of the reason for the failure The following procedure describes how to monitor notifications. ◆ To monitor notifications: 1.


2.

Select a running ESB Container containing an XML Service instance, right-click on the service-instance name, and select Notifications... . The Monitoring dialog box opens with its Notifications tab:


121

Chapter 5: Monitoring and Logging 3.

You can select one or more notifications, and for each notification, select Watch and select whether to watch: ■ By Component (ESB Container) ■ By Container (management container) ■

By Domain

The Sonic Management Console marks notifications that are being watched:

The Sonic Management Console opens a Notification Watcher. For general information on notifications and on watching notifications and viewing notification attributes, see the “Monitoring” chapter in the Progress SonicMQ Configuration and Management Guide. See also the Progress SonicMQ istrative Programming Guide and the Progress Sonic Event Monitor ’s Guide documentation for information on other options for tracking these notifcations.

122


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. the management container’s working directory. formation includes: ● Service-specific information — Includes state changes within the service itself ● Sonic XML Server-related information — Includes method parameters, inputs, and outputs You can turn on internal logging for debugging purposes. Set the Java system property com.sonicsw.xe.logging on the management container hosting the XML Service. In the Sonic Management Console’s Manage view, edit the container’s Properties and enter your Java system property settings on its Environment tab, using one or more of the following: ●

Script ■

■

Script.Actions ❑

Script.Actions.Get

❑

Script.Actions.Put

❑

Script.Actions.Remove

❑

Script.Actions.XQuery

❑

Script.Actions.XSLT

Script.Parser

●

Management.collections

●

Management.documents

●

Collections ■

Collections.Factory

■

Collections.Storage ❑

●

Collections.Storage.Utils

Utils ■

Utils.XPath

●

XMLService.message

●

XMLService.service

●

Archive


123


The following screen shows the Environment tab of a management container’s configuration:

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

124


Chapter 6

Performance Tuning XML Servers

Most s of Sonic XML Server experience high performance without tuning. This chapter contains suggestions that can optimize your XML Server configuration and application design for your applications’ patterns of data access. Because there can be trade-offs and tuning is highly application-specific, you should test your application to determine which suggestions are most effective. This chapter contains the following sections: ● “Tools for Tuning XML Servers” shows where tuning parameters are accessed. ● “Tuning XML Services and Collections” explains transactions and concurrency and describes how to tune action flows, XML Services, and collections. ● “Tuning Data Storage” contains suggestions for distributing documents, in collections, determining locations for collections, using message routing, tuning storage maintenance, and managing the transaction log. ● “XPath Expressions and XSLT Transformations” discusses ways to optimize XPath and XSLT performance.


125

Chapter 6: Performance Tuning XML Servers

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

126


Tools for Tuning XML Servers

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

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


127


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

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

128


Tools for Tuning XML Servers

Setting JVM System Properties on a Management Container Maintain JVM system properties for a management container through the Sonic Management Console by opening the container’s Properties, and then choosing the Environment tab, as shown:

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


129


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

Transactions and Concurrency Control Each Sonic XML Server contains a transaction scheduler that dynamically balances the resources required to begin and commit transactions as Sonic XML Server action flows are executed. Within an XML Service thread, each action flow executes within its own virtual transaction. This ensures that the data viewed and manipulated by the thread is correctly isolated from other threads that are executing their own virtual transactions. A datastore transaction is the actual physical transaction that commits changes in the datastore; it controls data locking and logging to manage concurrent access by multiple XML Service threads accessing the same datastore. The transaction scheduler allows several virtual transactions to execute within a single datastore transaction whenever this can done without compromising data consistency. The transaction scheduler ensures that: ● A virtual transaction commit operation does not return if any data it accessed or modified is not fully saved in the datastore through a full datastore transaction commit. ● Different threads that are executing read operations at about the same time can execute concurrently with minimal thread blocking. ● Threads that execute update operations run in exclusive mode. This avoids any possibility of inconsistency in XML data from update operations in other threads. This sharing of datastore transactions reduces the relative cost of transaction overhead per virtual transaction. It also improves response time because less thread synchronization is required. However, to ensure correct data consistency, it sometimes requires completed virtual transactions to be blocked until the underlying transaction is committed. This can increase the response time for the threads that are waiting. When more than one instance of a Sonic XML Service accesses data within the same collection, the underlying XML Server concurrency mechanisms ensure transactional integrity and a consistent data view. This management is performed by a system of lock coordination among XML Service processes.

130


Tuning XML Services and Collections

This system provides forward-caching of XML data in Sonic XML Server, independent of the storage location of the data. In addition, fine-grained fetching and writing of XML nodes allows XPath access to perform optimally with very large documents. This system has the following characteristics: ● Every XML Service accesses only committed, consistent data, even if many XML documents and collections are accessed. ● When there is no conflict, control of data and locking migrates from the Sonic XML Server datastore server to the data cache of the Sonic XML Service. XML Services then runs in-memory with a minimum of network access. In this manner, simultaneous read access is ed 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-demand—it is performed only for those blocks of data actually read or updated by Sonic XML Server. When an update operation is in progress, an XML Service in locking mode might have to wait for completion before it can acquire shared data. ● In nonlocking mode, the datastore server provides a time-consistent snapshot of data to one or more read transactions that might execute concurrently with an update transaction. This eliminates any lock waiting, though it means that read transactions do not see changes made by the overlapping update transactions.


131


Tuning Action Flows, Transactions, and XML Services The following suggestions and settings tune action flows, transactions, and XML services.

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

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

132



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

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


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.

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

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

134



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

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


135


Tuning XML Service Resources Each XML Service instance has the following resources: ● Address space — Mapped from the virtual memory range reserved for Sonic XML Server at startup. This allows XML Server to identify and reference XML nodes and metadata without having to allocate memory or fetch data. ● Data cache — Allocated within virtual memory and used to retain XML documents in memory across operations and transactions. ● Network connections — To the XML Server lock manager and datastore server. Collection data for each XML Service is retained in memory on a most recently used basis. Ensure that the size of the cache can comfortably hold the XML nodes and indexes that are repeatedly accessed. Also ensure that there is enough RAM on the system to accommodate the XML Services. Otherwise, the standard virtual memory facilities of the system start swapping, which eliminates many of the benefits of caching. The following settings describe how you can tune address space size, cache size, and cache space affinity to optimize cache performance.

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

136



Some transactions, such as adding an index to a large collection, automatically release address space in the middle of an operation. For certain unoptimized queries and for very long transactions, however, address space is progressively consumed during the transaction until the transaction is committed. In the worst case, the configured address space size is exhausted and a restartable exception is thrown. There are several ways you can avoid this: ● Increase the amount of address space allocated to the XML Service when you configure it in the Sonic Management Console. ● Add indexes to optimize queries and avoid lengthy sequential searches. For key operations, including creation of indexes and insertion into collections, XML Server dynamically releases address space during execution. This allows a single request to perform the operation even when the total amount of data managed exceeds the configured address space limit. To change this property, modify the Address Space Size setting for the service instance. See “Setting Properties on an XML Service Type Instance” on page 127 for more information. In rare cases, you might want to tune the internal trigger points for this address space release by setting the following environment variables for the container hosting the XML Service: ● XLN_INDEX_NODE_COUNT_AS_RELEASE controls how often address space is released as you create an index on a large collection (the default is 20,000 nodes). ● XLN_DIR_ENTRY_COUNT_AS_RELEASE controls address space release when deleting documents (the default is every 100 files deleted). To set these environment variables, use the Sonic Management Console’s Manage view to edit the container’s Properties and enter your settings on its Environment tab, as illustrated on page 124. For more information about environment settings, see the “Configuring Containers and Collections” chapter in the Progress SonicMQ Configuration and Management Guide.


137


Adjust Cache Size Suggestion: Adjust the XML Service cache size (specified by the Cache Size XML Service configuration property. Performance for updates and queries is sensitive to cache size. To determine the optimum cache size for your application, try to minimize the number of times the client must swap pages out of the cache and send them back to the server. Consider the following factors: ● Amount of data that is accessed — XML Services that are accessing or updating large amounts of data need larger caches. ● Amount of physical memory on a machine — Usually, it is desirable for the cache to stay in physical memory rather than to be swapped out to disk. ● Data access patterns — A large datastore of documents might have a relatively small number of documents that are regularly returned from queries or updated and might not require as large a cache. To change this property, modify the Cache Size setting for the service instance. See “Setting Properties on an XML Service Type Instance” on page 127 for more information.

Take Advantage of Cache Affinity When queries access documents that have already been retrieved and cached, query speed is improved. Grouping documents in collections so that queries retrieve cached data can enhance performance. For Progress Sonic ESB clients, a high level of cache affinity is ensured by routing requests to XML Service instances that are appropriately specialized in designated areas of the storage hierarchy. Cache affinity describes the degree to which data accessed within a program overlaps with data already retrieved on behalf of a previous request. Where there is high cache affinity, strong cache management architectures such as XML Server have a relative performance advantage. For an XML Service, the effectiveness of cache affinity has three levels: ● Cold access — A request accesses XML documents that have not been retrieved recently by this XML Service, or have been called back for another XML Service to update. The data must be retrieved from the datastore server and possibly from disk storage. (A fair amount of disk file caching occurs on the server side.) Cold access is typical of random queries against a collection.

138


Tuning XML Services and Collections ●

●

Warm access — The request involves data that has been retrieved by a prior transaction and is still within the XML Server’s data cache, but requires remapping of address space prior to use. Warm access is typical when: ■ A executes consecutive XPath expressions, XSL transformations, and update operations against the same document. ■ Successful routing rules funnel a large number of requests for a modest-size directory to a single XML Service instance. Hot access — Required data has already been accessed in the current transaction, and can be immediately used without any fetching or mapping of data.

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

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

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


139


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

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

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

140


Tuning Data Storage

Message Routing You can use the Sonic ESB Content-based Routing (CBR) service to route messages to the appropriate service instance for a document collection. You can define CBR routing rules to meet a broad range of scalability and concurrent access requirements. (For information on the CBR service, see “Implementing a Content-based Routing Service” in the Progress Sonic ESB Product Family: Developer’s 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 can control how out of date this view can become by adjusting the Transaction Open Interval for the service.


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


Wholesale

XQUERY 2000 operations/min

Policies

Read-only Services


Car

Update Service


Home Update Service


Life

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

142


Tuning Data Storage

Locations for Collection Typically, a system focuses on collections, and how they relate to actual disks and files on the network. The : ● 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 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 Developer’s 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.


143


Tuning Storage Maintenance The following are suggestions for scheduling tasks, backup, and compression to tune storage.

Do Maintenance on Collections Suggestion: Perform maintenance on collections for peak efficiency. Maintaining collections efficiently decreases the number of documents that queries must search through and also decreases the number of out of date results returned. There are two ways to maintain collection size: ● Manually removing documents ● Archiving documents

Compress Collections Suggestion: Compress collections through backup and restore. In a collection, Sonic XML Server organizes documents within internal directories that contain a thousand documents per directory. When documents are removed through timeto-live or are deleted by a DELETE action they are removed from the directory but not replaced. New documents are added to new directories, not old directories. Older directories will not contain the maximum number of documents. Therefore, collections that are subject to frequent document removal take up slightly more space per document than those that do not have frequent document removal.

Schedule Intensive Operations Suggestion: Schedule intensive operations in off-peak hours. Since all update intensive operations affect concurrency, delete operations are optimally performed in off peak hours. The same is true of documents removed from collections through the time-to-live (TTL) feature. Delete operations in a collection are often less time sensitive than updates or queries. It is possible to perform maintenance at a scheduled time every day. The time when it is performed depends on the time when the XML Service was started. (You can use Activation Daemons to schedule these operations. See “Using Activation Daemons” on page 78 for information on Activation Daemons.)

144


Tuning Data Storage

However, there is still a requirement to clean out or archive old data in a way that ensures continuous, scalable operation. Persistent XML can have many dependencies with indexes and storage structure. XML Server traverses every node within a document you are deleting. Deletion time scales with the total number of nodes deleted, plus the number of index entries that must be removed. You can also delete an entire collection in the Sonic Management Console without going through these fine-grained operations. (For more information, see the Progress Sonic ESB Product Family Developer’s 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 Developer’s Guide in the Eclipse help.

Managing the Transaction Log The transaction log, sonicxmlserver_install_dir\XMLDatabase\etc.log, is a binary log file that contains all transactions that have not yet been propagated to the XML data stores. Do not modify or delete this file. The transaction log can grow and affect performance. Moving the transaction log to an isolated disk with optimal sequential write performance can improve overall performance. Important If you decide to relocate the transaction log, Sonic Technical for

information on how to do this safely.


145


XPath Expressions and XSLT Transformations The Progress Sonic ESB Product Family: Developer’s Guide in the Eclipse help describes how to use XQuery and XSLT with Sonic XML Server. Both XSLT stylesheets and XQuery expressions include XPath expressions, and the performance of XPath expressions is an important part of overall XSLT or XQuery performance. For this reason, most of the suggestions offered for XPath optimization can be used for both XSLT and XQuery actions.

XPath Expressions Improving XPath performance begins with an analysis of application use cases that retrieve stored XML through XPath expressions. When you have a clear sense of the patterns of access, including relative size and frequency of XPath retrieval for specific XML nodes, you can identify areas for optimization. XPath expressions in XML Server are processed dynamically as they are ed to the XML Server XPath processor. The performance achieved when a given XPath request is executed depends on several factors: ● Time required to evaluate and optimize the XPath expression ● Efficiency of the optimized XPath execution tree, which in turn depends on: ■ Number of XML elements reachable from the target document ■ Use of indexes to optimize query constraints ■ XML Server caching of documents and indexes ● Data extraction, sorting, and serialization that must be done on the return set The following suuggestions can improve XPath performance.

Match Indexes to Queries Suggestion: Design indexes to match queries as closely as possible. Sonic XML Server uses a value index, which locates all of the nodes that share: ● A common ancestor element ● A specified XPath key path ● Matching text or floating-point data value for nodes matching that key path

146


XPath Expressions and XSLT Transformations

A value index can quickly compute the subset of nodes that match an XPath predicate. The more closely the XPath expression matches an existing value index, the more certain you are that the XPath processor can pick up the index in optimization. Indexing is not required in all situations. Unlike most XML/RDBMS solutions, XML Server retains the XML DOM structure within storage. This means that many XPath operations involve simple in-memory DOM traversals that execute extremely fast, even without an index. Retrieving child nodes from an element or locating parent nodes occurs at in-memory speeds and does not require indexing. However, selecting a small set of XML nodes from a large document or collection can be greatly enhanced with appropriate indexing. For example: //Enterprise/personnelData/[lastName=”Smith”] collection(“foo”) //a/b[c=”Fred”] INDEX on collection “foo” INDEX path = //a/b Key path =c

Control Results Set Size Suggestion: Control the XPath result set size. The data returned by an XPath expression is well defined by the XPath string and the DOM structure of the document being queried. The size of the results has an important impact on XPath performance because: ● All child nodes included in the result must be explicitly retrieved from the collection. Address space reserved for returned nodes cannot be dynamically released during the transaction, eventually limiting the size of the return set. ● If the operation returns an XML string, all tags and text data must be accumulated in an in-memory buffer. ● The amount of work required by the application to process results is generally proportional to their size.

Analyze Whether Excess Nodes Are Returned. Suggestion: Analyze the nodes to be returned. The best way to control result set size is to examine the XPath expression to confirm that all the nodes returned are required by the application. For example, if you want only the authors of books with a certain title:


147

Chapter 6: Performance Tuning XML Servers ●

●

●

The query, collection("bookstore")//book[title = "On Walden Pond"], is too broad because it returns all book information, not just the authors. The query, collection("bookstore")//book/author[../Title = “On Walden Pond”], returns only author elements, but it requires the query engine to check for a title match for each author. The query, collection,("bookstore")//book[title = "On Walden Pond"]/author, immediately selects the correct books, and then returns only the author information.

XSLT Transformations XSLT stylesheets transform XML documents into another schema. For example, another dialect of XML for business process integration. XSLT performs this operation on demand within XML Server, and makes the result accessible to the action flow. You can optionally return the output or save it in a collection. In general, the time required to complete a transformation is a function of the size of the input document and the complexity of the XSLT stylesheet. The steps in XSLT processing include: 1.

Preprocess the XSLT file to create an optimized stylesheet.

2.

Select nodes from the XML source document, based on the XPath expressions specified in the XSLT selection syntax. (Some XPath query optimization occurs here, as discussed previously.)

3.

Match selected nodes against the patterns in the XSLT templates.

4.

Generate the output document.

The optimized stylesheet object is a transient structure that resides on the server only for the lifetime of the current transaction. The following suuggestions can improve XSLT performance.

XSLT Node Selection Suggestion: Narrow the result set ed to the transformation engine Selection of the input source is important for efficient transformation. To the degree you narrow the result set ed to the transformation engine, you reduce the time consumed in pattern matching and generation. Examine the query statements in your XSLT stylesheet to restrict the number and size of the XML nodes returned to the smallest workable set. 148


XPath Expressions and XSLT Transformations

XSLT Template Matching Suggestion: Perform filtering in the selection expression rather than the template matching expression Depending on the complexity of the XSLT stylesheet, matching the XPath expression of the template to the selected source data can require intensive computing. You should try to ensure that any filtering that must be done is achieved in the selection XPath expression rather than in the template matching XPath expression. Suggestion: Make XSLT template matching as straightforward as possible. Use simple XPath expressions that can achieve node comparisons without requiring a lot of node traversal. Try to avoid recursive XSLT pattern matching. Additional information about tuning XPath expressions is available in “XPath Expressions and XSLT Transformations” on page 146.

XSLT Output Generation Generating the output document tends to demonstrate predictable, scalable performance. If the output is stored within Sonic XML Server, rather than in subsequent script actions or returned from scripts, consider that: ● Generating the output takes longer because of XML Server DOM calls that are required to construct the document. ● Subsequent updates and queries should generally perform better because of XML Server caching. ● The application is responsible for synchronizing any changes, that is, regenerating the output document if any of the inputs have changed significantly.


149


150


Chapter 7

Backing Up and Restoring Document Collections

The Progress Sonic XML Server backup and restore utilities provide protection from unintended data corruption or data loss. These utilities full and incremental backup and restoration of document collections. Chapter 7 describes these utilities in the following sections: ● “Backing Up Sonic XML Server Document Collections” describes how to perform full and incremental backups of Sonic XML Server document collections. ● “Restoring Sonic XML Server Document Collections” describes how to restore Sonic XML Server document collections.


151

Chapter 7: Backing Up and Restoring Document Collections

Backing Up Sonic XML Server Document Collections To implement backup procedures for the Sonic XML Server document collections at your site, you can use a combination of backup operations: ● Full backup — Backs up specified XML document collections. ● Incremental backup — For given XML document collections, backs up all documents that changed since the last full backup or incremental backup at a lower level. To design and implement a backup routine for your site, follow these steps: 1.

Design a backup schedule. See “Deg a Backup Schedule” on page 152.

2.

Choose locations for backup-related files. See “Files Generated by the Backup and Restore Utilities” on page 155.

3.

Make a full backup. See “Performing Full Backup” on page 157.

4.

For each subsequent day in the backup schedule, perform the backup operation for that day. See “Performing Full Backup” on page 157 and “Performing Incremental Backup” on page 158.

Deg a Backup Schedule Incremental backup can reduce the amount of data that needs to be backed up, particularly for Sonic XML Server document collections with a relatively small number of modifications. Note that using incremental backup can increase the time required for restoring the XML data stores. A typical backup schedule assigns backup operations to each day of the week. For each incremental backup operation, it specifies the backup level to use. To follow the schedule, you must perform, for each day of the week, the operations assigned to that day. You should perform each day’s backup operations during a low traffic time period, that is, a time period during which there is relatively little access to the Sonic XML Server document collections being backed up. Level 0 specifies a full backup. You specify a backup level from 1 to 9 for each incremental backup. Documents modified since the last backup at a lower level are copied to the backup image.

152


Backing Up Sonic XML Server Document Collections

You can specify XML document collections that were modified since the last backup at a lower level be copied to the backup image. For example, you could perform a level 2 backup on Monday, followed by a level 4 backup on Tuesday. A subsequent level 3 backup on Wednesday would contain all XML documents modified or added since the level 2 (Monday) backup. To perform incremental backups, you must consider what levels to use, and when to back up at each level. Consider: ● Amount of data backed up — Increasing the backup level from one day to another can decrease the amount of data that must be backed up. ● Complexity of restoring — Increasing the backup level from one day to another can increase the number of backup images that must be restored. The following examples show two different backup schedules: ● The schedule in Table 4 consists of a full backup on Sunday, and an incremental backup every subsequent day of the week that backs up every directory that has changed since the previous day’s backup. This strategy can result in the backing up of less data for a given week. But restoration can be more complex than with the schedule in Table 5. Restoration to Friday, for example, requires the restoration of the images from Sunday through Friday (six images in all). :

Table 4. Sample Backup Schedule with Daily Increments

Day

Level

Description

Sunday

0 (full)

Full backup of all specified Sonic XML Server document collections

Monday

1

Back up all documents that changed since Sunday

Tuesday

2

Back up all documents that changed since Monday

Wednesday

3

Back up all documents that changed since Tuesday

Thursday

4

Back up all documents that changed since Wednesday

Friday

5

Back up all documents that changed since Thursday

Saturday

6

Back up all documents that changed since Friday


153

Chapter 7: Backing Up and Restoring Document Collections ●

The schedule in Table 5 consists of a full backup every Sunday, followed by incremental backups Monday through Wednesday. These include documents that changed since Sunday. They are followed by incremental backups Thursday through Saturday that back up directories that have changed since Wednesday. This strategy can result in backing up more data in a given week. But restoration is simpler than with the first schedule. Restoration to Friday, for example, requires the restoration of images from Friday, Wednesday, and Sunday (three images in all). Table 5. Sample Backup Schedule with Biweekly Increments

154

Day

Level

Description

Sunday

0 (full)

Full backup of all specified Sonic XML Server document collections

Monday

2


Tuesday

2


Wednesday

1


Thursday

2


Friday

2


Saturday

2




Files Generated by the Backup and Restore Utilities Sonic XML Server’s backup utility generates or updates the following types of files: ● Backup image files — Images of documents in the Sonic XML Server document collections backed up. You specify a path name for the directory to contain the image files when you perform a full or incremental backup. ● Backup record file — Internally used information about the backup operations that have been performed. When you perform a full or incremental backup, you specify a path name for the record file. The filename should have the file extension, .irf. A backup operation creates the record file if it does not exist; otherwise it modifies the existing record file. When you perform an incremental backup, the record file must be the same file that served as the record file for the associated full backup. ● Log files — The backup and restore utilities create log files in the current directory with information about the result of the operations. The log file contents are also sent to the console. The log files are removed, if present, at the beginning of the backup/restore script. Therefore, running the tools a second time deletes the logs from the first run. Be sure that the following is true for both the image file and record file: ● These files should be stored on a separate device from the Sonic XML Server document collections being backed up and from the transaction log. This protects you in the event of disk crash. It also allows reads to occur on the source disk and writes on the target disk, which results in a faster backup. ● These files must be stored on a device that contains sufficient space. The image files can require several times the space occupied by the document collections being backed up. If you use full backup on every nth day and incremental backup on all other days, and if all document collections of all documents change each day, then the backup image files will need about n times the size of the data stores being backed up.


155


Using the Backup Utility The Sonic XML Server backup utility is invoked by a batch file, backup.bat, on Windows and a shell script, backup.sh, on UNIX. Entering backup in a console in the sonicxmlserver_install_dir\bin directory without options prints a usage message: backup [-all | ([-meta] [-service <servicename>] [-coll ]) [-path <metadatapath>] [-verbose] [-level ] [-incfile ] -dir

Command line options can be abbreviated to their first letter, for example -v for -verbose. Square brackets indicate optional switches. Table 6 lists the arguments for the backup utility. Table 6. Backup Utility Arguments

156

Argument

Description

-all

Back up all document collections and metadata in the installation. An installation is defined by a metadata location.

-meta

Back up only configuration metadata.

-service servicename

Back up all document collections created by the specified service instance.

-coll collectionname

Back up one, specified document collection.

-path metadatapath

Path to the metadata store, if it is not the default location.

-verbose

Verbose output.

-level inc-level

Incremental backup level, an integer from 0 to 9. The default is 0, a full backup.

-incfile inc-file

Incremental backup record data file.

-dir backupdir

Directory for backup data. (Required.)



Performing Full Backup When performing a backup, the target directory (E:\BU1.1.02 in the following examples) must not already contain any backups of the Sonic XML Server document collections that need to be backed up. Use a different directory from the previous run of backup, unless the backup images from previous runs have been moved. In the following examples, the -level option specifies level 0, a full backup. The following command performs a full backup of all Sonic XML Server document collections for a service named service1. It generates the backup record file, E:\BU1.1.02\service1.irf, and generates an image file in the directory, E:\BU1.1.02. backup -service service1 -incfile E:\BU1.1.02\service1.irf -level 0 -dir E:\BU1.1.02

The following command performs a full backup of the configuration metadata. It updates the backup record file, E:\BU1.1.02\service1.irf, and generates image files in the directory, E:\BU1.1.02. backup -meta -incfile E:\BU1.1.02\service1.irf -level 0 -dir E:\BU1.1.02

The following command performs a full backup of all XML data stores in the current installation. backup -all -incfile E:\BU1.1.02\service1.irf -incfile 0 -dir E:\BU1.1.02

The following command performs a full backup of the document collection named employee. backup -coll employee -incfile E:\BU1.1.02\service1.irf -level 0 -dir E:\BU1.1.02


157


Performing Incremental Backup Performing incremental backup is like performing full backup, except that you specify a nonzero level with the -level option, for example: backup -service service1 -incfile E:\BU1.1.02\service1.irf -level 2 -dir E:\BU1.2.02

backup -meta -incfile E:\BU1.1.02\service1.irf -level 2 -dir E:\BU1.2.02

When you perform incremental backup, the backup record file that you specify with the -i option must be the same file that served as backup record file for the associated full backup.

Restoring Sonic XML Server Document Collections The restore utility restores Sonic XML Server document collections from a backup image, restoring either the entire backup set or selected document collections within the set. Procedures vary based on whether you are restoring a full or incremental backup: ● If you performed full backup, restore the document collections from the latest full backup images made prior to the time to which you want to restore. (See “Restoring from Full Backup Images” on page 160.) ● If you performed incremental backup, restore from the relevant incremental backup images. (See “Restoring from Incremental Backup Images” on page 161.) Important To restore a document collection that was removed, you must also restore the metadata

by using -meta and -coll. Using -coll alone is not sufficient.

158


Restoring Sonic XML Server Document Collections

Using the Restore Utility The Sonic XML Server restore utility is invoked by a batch file, restore.bat, on Windows and a shell script, restore.sh, on UNIX. The script is located in the bin directory of the installation. Entering restore in a console in the sonicxmlserver_install_dir\bin directory without options prints a usage message: restore [-all | ([-meta] [-service <servicename>] [-coll ]) [-path <metadatapath>] [-remap] [-verbose] -dir

Command line options can be abbreviated to their first letter, for example -v for -verbose. Square brackets indicate optional switches. Table 7 lists the arguments for the restore utility. Table 7. Restore Utility Arguments

Argument

Description

-all

Restore all document collections and metadata in the installation. An installation is defined by a metadata location.

-meta

Restore only configuration metadata.

-service servicename

Restore all document collections for the specified service instance.

-coll collectionname

Restore one, specified document collection.

-path metadatapath

Path to the metadata store to write to if you want to restore to a different metadata location than the backup destination.

-remap

Perform interactive remapping of host/directory for services. Also use the -path metadatapath option to restore the metadata as well.

-verbose

Verbose output.

-dir backupdir

Directory containing backup data (required).


159


Restoring from Full Backup Images To restore from full backup images, use the restore utility and specify the following: ● Document collections to restore ● Directory containing the backup images of the document collections to restore. These are the images that are generated by backup when you perform full backup. The following example restores all the backup images contained in the directory, E:\BU1.1.02. restore -all -dir E:\BU1.1.02

If you restore to a different host, use the –remap option along with the –service or -coll option instead of the –all option. Otherwise, if you run backup using the -all option on host A and then restore on host B, restore restores the metadata and points to the original document collections on the host A. This results in both installations pointing to the same document collections. Changes made to the document collections in either installation are recorded in the same document collections on host A. Important The –remap option works only when backup and restore are used on the same platform.

To restore both the collections and the metadata to a new location, you must use both -remap and -path (to remap the location of the metadata). The following example restores all backup images of Sonic XML Server document collections created by service1 contained in the directory, E:\BU1.1.02. restore -service service1 -dir E:\BU1.1.02

160


Restoring Sonic XML Server Document Collections

Restoring from Incremental Backup Images To restore from incremental backup images from a given day, use the restore utility and specify: ● Document collections to restore. These must be document collections that you restored from full backup images. ● Directory containing the backup images of the document collections to restore. These are the images that were generated by backup when you performed incremental backup on the given day. To determine which days’ backup images to restore, construct a list of days: 1.

Identify the day to which you want to restore on the list.

2.

Consider each day that is earlier than the day to which you want to restore and later than the latest prior full backup. Consider each such day in reverse order, from latest to earliest. For each such day, if its backup level is lower than the backup level of the list’s last day, add the day to the end of the list.

Restore the images from each day on the list, working in reverse order, starting with the last day on the list. For example, you could perform the following backups: 1.

Full backup on Monday

2.

Level 5 on Tuesday

3.

Level 6 on Wednesday

4.

Level 2 on Thursday

5.

Level 4 on Friday

To restore to Friday, start by putting Friday on the list. Then consider each previous day, Thursday, Wednesday, and Tuesday. Thursday’s level is lower than Friday’s level, so Thursday goes on the list. Wednesday’s level is not lower than Thursday’s level, so it does not go on the list. Finally, Tuesday’s level is not lower than Thursday’s 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 Thursday’s images, and then restore from Friday’s images.


161


162


Part III

Configuring Database Services

Part III contains the following chapters: ● Chapter 8, “Using the Database Service JDBC Drivers” ● Chapter 9, “Driver Connection Properties and Data Types by Database Brand” ● Chapter 10, “SQL Escape Sequences for JDBC” ● Chapter 11, “Configuring SQL Server Windows Authentication” Note This section provides information for the JDBC drivers bundled with Progress Sonic

Database Service. If your installation uses a different JDBC Driver, consult the vendor’s documentation for their configuration guidelines.


163

164


Chapter 8

Using the Database Service JDBC Drivers

Chapter 8 includes information on failover, load balancing, and error handling for Progress Sonic Database Service connections. This chapter includes the following sections: ● “JDBC Driver Connection Properties and the Database Service” — Explains how to configure and deploy third-party JDBC drivers for use with Sonic Database Service. ● “Load Balancing, Failover, and Connection Retry” — Explains how these features are implemented and provides references to appendixes where the connection properties for each of the JDBC drivers are listed. ● “Using Activation Daemons” — Shows how to use Activation Daemons with Database Services.


165

Chapter 8: Using the Database Service JDBC Drivers

JDBC Driver Connection Properties and the Database Service The Database Service reconnect timeout might expire while the JDBC driver failover or retry is taking place. In this event, if the JDBC driver failover or connection retry operations exceed the Database Service connection Timeout limit, the connection will not succeed and the associated Database Service operation will fail, resulting in an error message being sent to the rejected message endpoint (RME.) The Database Service reconnect is not the same as the JDBC driver connection retry. The Database Service is not aware of a connection failure until the JDBC driver connection retry is unsuccessful. When the Database Service attempts a reconnection, the JDBC driver acts as if this is a new database connection and the driver load balancing, failover, and connection retry parameters are all used as if an initial database connection is being established.

Load Balancing, Failover, and Connection Retry To optimize performance, you can implement client load balancing, connection failover, and connection retry in your Database Service connection properties. To do this, specify both primary and alternate servers in the connection URL. The following sections explain these features: ● “Client Load Balancing” on page 168 ● “Connection Failover” on page 169 ● “Connection Retry” on page 170

166


Load Balancing, Failover, and Connection Retry

For details on configuring load balancing, failover, and connection retry properties for each of the JDBC drivers available with Sonic Database Service, see the following sections: Table 8. Documentation for JDBC Driver Connection Properties and Alternate Servers

JDBC Driver

Connection Properties Documentation

Progress Open Edge

●

“Progress OpenEdge Database” on page 176

●

“Progress OpenEdge Connection Failover Properties” on page 181

●

“Specifying Alternate Servers for the Progress OpenEdge Driver” on page 182

●

“Progress OpenEdge Driver Data Types” on page 184

●

“DB2 Driver Connection Properties” on page 185

●

“DB2 Driver Connection Failover Properties” on page 198

●

“Specifying Alternate Servers for the DB2 Driver” on page 198

●

“DB2 Driver Data Types” on page 200

●

“Informix Driver Connection Properties” on page 201

●

“Informix Driver Connection Failover Properties” on page 209

●

“Specifying Alternate Servers for the Informix Driver” on page 209

●

“Informix Driver Data Types” on page 210

●

“Oracle Driver Connection Properties” on page 212

●

“Oracle Driver Connection Failover Properties” on page 223

●

“Specifying Alternate Servers for the Oracle Driver” on page 224

●

“Oracle Driver Data Types” on page 225

●

“Microsoft SQL Server Driver Connection Properties” on page 227

●

“Microsoft SQL Server Driver Connection Failover Properties” on page 238

●

“Specifying Alternate Servers for the Microsoft SQL Server Driver” on page 238

●

“Microsoft SQL Server Driver Data Types” on page 240

●

“Sybase Driver Connection Properties” on page 242

●

“Sybase Driver Connection Failover Properties” on page 252

●

“Specifying Alternate Servers for the Sybase Driver” on page 252

●

“Sybase Driver Data Types” on page 254

DB2

Informix

Oracle

Microsoft SQL Server

Sybase


167


Client Load Balancing Client load balancing helps distribute new connections to multiple servers in your environment so that no one server is overwhelmed with connection requests. When client load balancing is enabled, the order in which primary and alternate database servers are tried is random. For example, suppose that client load balancing is enabled as shown in Figure 1.

3

Database Server A (Primary)

Sonic Database Service

1

2

Database Server B (First Alternate)

Database Server C (Second Alternate)

Figure 1. Client Load Balancing Example

In the example in Figure 1, when client load balancing is enabled the Database Service first attempts to connect to Database Server B (1). The Database Service then attempts a connection to Database Server C (2), followed by a connection attempt to Database Server A (3). In contrast, if client load balancing was not enabled in this scenario, each database server would be tried in sequential order, primary server first, then each alternate server based on their entry order in the alternate servers list. To use client load balancing, specify the following properties in the form property=value in your connection URL: ● LoadBalancing — Set this property to true to enable load balancing. ● AlternateServers — See “Specifying Primary and Alternate Servers” on page 172.

168



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.

1

Database Server A (Primary)

Sonic Database Service

2

3

Database Server B (First Alternate)

Database Server C (Second Alternate)

Figure 2. Connection Failover Example

In the example shown in Figure 2, the Database Service first attempts to connect to the primary database server, Database Server A (1). If connection failover is enabled and Database Server A fails to accept the connection, the Database Service then attempts to connect to Database Server B (2). If that connection attempt also fails, the Database Service attempts to connect to Database Server C (3).


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 information is invalid, for example, the driver does not try to connect to the next database server in the list and generates an exception. Connection failover provides protection for new connections only and does not preserve states for transactions or queries. To use connection failover, see the appropriate section for your database for a list of property=value pairs to add to your connection URL: ● ● ● ● ● ●

“Progress OpenEdge Connection Failover Properties” on page 181 “DB2 Driver Connection Failover Properties” on page 198 “Informix Driver Connection Failover Properties” on page 209 “Oracle Driver Connection Failover Properties” on page 223 “Microsoft SQL Server Driver Connection Failover Properties” on page 238 “Sybase Driver Connection Failover Properties” on page 252

Connection Retry Connection retry allows the JDBC driver to retry connections to a list of database servers (primary and alternate) until a successful connection is established. Use the ConnectionRetryCount and ConnectionRetryDelay properties to enable and control how connection retry works. In the following examples for the different JDBC drivers, if a successful connection is not established on the driver’s first 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 through the list of servers, the driver makes another 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 es.

170



Connection Retry Example for Progress OpenEdge Driver jdbc:sonic::datadirect:openedge://server1:2003;HostName=TestServer; DatabaseName=TestServer;=test;=secret; AlternateServers=(server2:2003;DatabaseName=TEST2,server3:2003; DatabaseName=TEST3);ConnectionRetryCount=2;ConnectionRetryDelay=5

Connection Retry Example for DB2 Driver jdbc:sonic:db2://server1:50000;DatabaseName=TEST; AlternateServers=(server2:50000;DatabaseName=TEST2, server3:50000;DatabaseName=TEST3);ConnectionRetryCount=2; ConnectionRetryDelay=5

Connection Retry Example for Informix Driver jdbc:sonic:informix://server1:2003;InformixServer=TestServer; DatabaseName=TestServer; AlternateServers=(server2:2003;DatabaseName=TEST2,server3:2003; DatabaseName=TEST3);ConnectionRetryCount=2; ConnectionRetryDelay=5

Connection Retry Example for Oracle Driver jdbc:sonic:oracle://server1:1521;ServiceName=TEST; AlternateServers=(server2:1521;ServiceName=TEST2, server3:1521;ServiceName=TEST3);ConnectionRetryCount=2; ConnectionRetryDelay=5

Connection Retry Example for Microsoft SQL Server Driver jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST; AlternateServers=(server2:1433;DatabaseName=TEST2, server3:1433;DatabaseName=TEST3);ConnectionRetryCount=2; ConnectionRetryDelay=5


171


Connection Retry Example for Sybase Driver jdbc:sonic:sybase://server1:4100;DatabaseName=TEST; AlternateServers=(server2:4100;DatabaseName=TEST2, server3:4100;DatabaseName=TEST3);ConnectionRetryCount=2; ConnectionRetryDelay=5

Specifying Primary and Alternate Servers The Sonic Database Service JDBC drivers allow you to specify a list of alternate database servers that are tried at connection time if the primary server is not accepting connections using the AlternateServers property. Connection attempts continue until a connection is successfully established or until all the database servers (primary and alternate) have been tried the specified number of times. Connection information for alternate servers is specified using the AlternateServers property in a connection URL. The value of the AlternateServers property is a string that has the format: (servername1[:port1][;property=value[;...]],servername2[:port2] [;property=value[;...]],...)

where: ●

is the IP address or server name of the first alternate database server, the IP address or server name of the second alternate database server, and so on. The IP address or server name is required for each alternate server entry. port1 is the port number on which the first alternate database server is listening, port2 is the port number on which the second alternate database server is listening, and so on. Port numbers are optional for each alternate server entry. If unspecified, the port number specified for the primary server is used. If a port number is unspecified for the primary server, the default port number is used (see Table 8 on page 167 to locate the appendix containing information on the default PortNumber values for the JDBC drivers). property=value is an optional connection property, based on the JDBC driver to which you are connecting. servername1

servername2 is

●

●

172



See the following sections for examples that describe how to specify primary and alternate servers for different JDBC drivers: ● “Specifying Alternate Servers for the Progress OpenEdge Driver” on page 182 ● “Specifying Alternate Servers for the DB2 Driver” on page 198 ● “Specifying Alternate Servers for the Informix Driver” on page 209 ● “Specifying Alternate Servers for the Oracle Driver” on page 224 ● “Specifying Alternate Servers for the Microsoft SQL Server Driver” on page 238 ● “Specifying Alternate Servers for the Sybase Driver” on page 252

Using Activation Daemons Using an Activation Daemon is a way to launch new containers as spawned processes of the container hosting the Activation Daemon. This allows new containers to be launched by remote istrative clients without the having to log on to that host. A typical use would be to have the container hosting the Activation Daemon launched as a Windows service on Windows platforms or a startup process under UNIX. An Activation Daemon monitors the health of its spawned containers and, depending on configured rules, restarts those containers upon failure. Normally one Activation Daemon is deployed per host. Multiple Activation Daemons can be created per domain. Containers can be launched by the Activation Daemon: ● At Activation Daemon startup time ● At a configured time ● After a container failure (up to a configurable number of retries) ● On demand from the Sonic Management Console or via the Activation Daemon’s management API You can create and configure an Activation Daemon to start an ESB Container hosting a Database Service. The steps required to create, configure, and test the Activation Daemon are: 1.

Create an Activation Daemon

2.

Add the Activation Daemon to a management container

3.

Add a container to an Activation Daemon’s activation list

“Using Activation Daemons” on page 78 provides information about how to complete the steps to create and configure an Activation Daemon to start an ESB Container hosting a service. Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

173


174


Chapter 9

Driver Connection Properties and Data Types by Database Brand

This chapter contains driver connection properties, connection failover properties, and driver data types for the following database brands: ● “Progress OpenEdge Database” ● “DB2” ● “Informix” ● “Oracle” ● “Microsoft SQL Server” ● “Sybase”


175

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

Progress OpenEdge Database The following sections describe settings for the Sonic Database Service’s Progress OpenEdge driver: ● “Progress OpenEdge Connection Properties” ● “Progress OpenEdge Connection Failover Properties” ● “Specifying Alternate Servers for the Progress OpenEdge Driver” ● “Progress OpenEdge Driver Data Types” See the DataDirect Connect for JDBC Progress OpenEdge Driver ’s Guide and Reference for more information.

Progress OpenEdge Connection Properties Table 9 describes the JDBC connection properties ed by the Progress OpenEdge driver. The properties have the format: property=value Table 9. Connection Properties for the Progress OpenEdge Driver

Property

Description

AlternateServers

A comma-separated list of alternate database servers that the driver will try to connect to if the primary database server is unavailable. The value of this property is a string that specifies each alternate server. This string has the format:

Default: No default Data type: String

(servername1[:port1][;property=value],servername2[:port2][;property=value],...)

The server name is required for each alternate server entry. Port number and connection properties (property=value) are optional for each alternate server entry. If the port is unspecified, the port number of the primary server is used. The driver only allows one optional property, DatabaseName. For example: jdbc:datadirect:openedge://server1:4100; DatabaseName=TEST;=test;=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 OpenEdge Database Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

ConnectionRetryCount

The number of times the driver retries connections to the primary database server, and if specified, alternate servers until a successful connection is established. Valid values are 0 and any positive integer.

Default: 5 Data type: int

If set to 0, the driver does not try to reconnect after the initial unsuccessful attempt. For example, in the case where the following properties are specified: AlternateServers=(server2:2003,server3:2003,server4:2003)

and ConnectionRetryCount=1

If a connection is not successfully established on the driver’s first through the list of database servers, the driver retries all the servers in the list only once. If an application sets a timeout value (for example, using DataSource.Timeout or DriverManager.Timeout), the timeout takes precedence over this property. For example, if the timeout expires, any connection attempts to alternate servers stop. If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. The ConnectionRetryDelay property specifies the wait interval, in seconds, used between attempts. ConnectionRetryDelay Default: 1 Data type: int

The number of seconds the driver waits before retrying connections to the primary database server, and if specified, alternate servers when ConnectionRetryCount is set to a positive integer. For example, in the case where the following properties are specified: AlternateServers=(server2:2003,server3:2003,server4:2003)


and ConnectionRetryDelay=3

If a connection is not successfully established on the driver’s first through the list of database servers, the driver retries the list of servers twice. It waits 3 seconds between the first connection retry attempt and the second connection retry attempt. If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time.


177

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

DatabaseName

The name of the database to which you want to connect.

Default: No default Data type: String HostName

The name of the Progress OpenEdge database server to which you want to connect.

Default: No default Data type: String

Specifies either the IP address or the server name (if your network s named servers) of the primary database server. For example, 122.23.15.12 or HostName. This property is ed 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 OpenEdge Database Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

LoadBalancing

{true | false}

Default: false

Determines whether the driver will use client load balancing in its attempts to connect to a list of database servers (primary and alternate). The list of alternate servers is specified by the AlternateServers property.

Data type: boolean

If set to true, client load balancing is used and the driver attempts to connect to the list of database servers (primary and alternate servers) in random order. If set to false (the default), client load balancing is not used and the driver connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified). For example, in the case where the following properties are specified: AlternateServers=(server2:4100,server3:4100,server4:4100)

and LoadBalancing=true

The driver randomly selects from the list of primary and alternate servers which server to connect to first. If that connection fails, the driver again randomly selects from this list of servers until all servers in the list have been tried or a connection is successfully established. MaxPooledStatements Default: 0 Data type: int

The maximum number of pooled prepared statements for this connection. Setting MaxPooledStatements to an integer greater than zero (0) enables the Progress OpenEdge driver’s internal prepared statement pooling, which is useful when the driver is not running from within an application server or another application that provides its own prepared statement pooling. If set to a positive number, the driver uses that value to cache a certain number of prepared statements created by an application. For example, if the value of this property is set to 20, the driver caches the last 20 prepared statements created by the application. If the value set for this property is greater than the number of prepared statements used by the application, all prepared statements created by the application are cached. Because CallableStatement is a sub-class of PreparedStatement, CallableStatements also are pooled.

REQUIRED Default: No default Data type: String

The case-sensitive used to connect to your OpenEdge database. A is required only if security is enabled on your database. If so, your system to obtain your . The is automatically encrypted.


179

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 9. Connection Properties for the Progress OpenEdge Driver (continued)

Property

Description

PortNumber

The T port of the primary database server that is listening for connections to the Progress OpenEdge database.

REQUIRED Default: Varies with operating system

This property is ed only for DataSource connections.

Data type: int SpyAttributes Default: No default Data type: String

Enables DataDirect Spy, a tool that can be used to log detailed information about calls issued by a running application to any DataDirect Connect for JDBC driver. The format for the value of this property is: (spy_attribute[;spy_attribute]...)

where spy_attribute is any valid DataDirect Spy attribute. For example: SpyAttributes=(log=(file)/tmp/spy.log;linelimit=80)

logs all JDBC activity to a file using a maximum of 80 characters for each line. NOTE: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded by the Java escape character, a backslash. For example: log=(file)C:\\temp\\spy.log. DataDirect Spy is not enabled by default. REQUIRED Default: No default

The case-insensitive name used to connect to your OpenEdge database. A name is required only if security is enabled on your database. If so, your system to get your name.

Data type: String

180


Progress OpenEdge Database

Progress OpenEdge Connection Failover Properties Table 10 summarizes the connection properties that control how connection failover works with the Database Service Progress OpenEdge driver. See Table 9 for details about configuring each property. Table 10. Connection Failover Properties for the Progress Open Edge Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each server is required. Port number and the DatabaseName connection property are optional. If the port number is unspecified, the port number specified for the primary server is used.


Number of times the driver retries the primary database server, and if specified, alternate servers until a successful connection is established. The default is 5.

ConnectionRetryDelay

Wait interval, in seconds, between connection retry attempts when the ConnectionRetryCount property is set to a positive integer. The default is 1.

DatabaseName

Name of the Progress OpenEdge database server to which you want to connect.

LoadBalancing

Sets whether the driver will use client load balancing in its attempts to connect to the list of database servers (primary and alternate). If client load balancing is enabled, the driver uses a random pattern instead of a sequential pattern in its attempts to connect. The default is false (client load balancing is disabled).

PortNumber

Port listening for connections on the primary database server. This property is ed 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.


181


Specifying Alternate Servers for the Progress OpenEdge Driver The following connection URL for the Progress OpenEdge driver specifies connection information for the primary and alternate servers: jdbc:datadirect:openedge://server1:2003;HostName=TestServer; DatabaseName=TestServer;=test;=secret; AlternateServers=(server2:2003;HostName=TestServer2,server3:2003)

In this example: ...server1:2003;HostName=TestServer; DatabaseName=TestServer...

is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property. For example: ...;AlternateServers=(server2:2003; HostName=TestServer2,server3:2003)

Similarly, connection information for the primary server specified using a JDBC data source would look something like this: OpenedgeDataSource mds = new OpenedgeDataSource(); mds.setDescription("My OpenedgeDataSource"); mds.setServerName("server1"); mds.setPortNumber(2003); mds.setHostName("TestServer"); mds.setDatabaseName("TestServer"); mds.set("test"); mds.set("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 OpenEdge Database

Using the AlternateServers Property Connection information for alternate servers is specified using the AlternateServers property with either a connection URL through the JDBC Driver Manager or a JDBC data source. The value of the AlternateServers property is a string that has the format: (servername1[:port1][;property=value[;...]],servername2[:port2] [;property=value[;...]],...)

where: is the IP address or server name of the first alternate database server, servername2 is the IP address or server name ofthe second alternate database server, and so on. The IP address or server name is required for each alternate server entry. servername1

port1 is

the port number on which the first alternate database server is listening, port2 is the port number on which the second alternate database server is listening, and so on. The port number is optional for each alternate server entry. If unspecified, the port number specified for the primary server is used.

property=value is either of the following connection properties: DatabaseName or HostName. These connection properties are optional for each alternate server entry. For example: jdbc:datadirect:openedge://server1:2003;HostName=TestServer; DatabaseName=TestServer;=test;=secret; AlternateServers=(server2:2003;HostName=TestServer2; DatabaseName=TestServer,server3:2003)

If you do not specify an optional connection property in an alternate server entry, the connection to that alternate server uses the property specified in the URL. For example, if youspecify HostName=TestServer and DatabaseName=TestServer for the primary server, but do not specify the HostName and DatabaseName properties in the alternate server entry as shown in the following URL, the driver uses the HostName and DatabaseName specified for the primary server and tries to connect to the TestServer database on the Progress OpenEdge server TestServer: jdbc:datadirect:openedge://server1:2003;HostName=TestServer; DatabaseName=TestServer;AlternateServers=(server2:2003,server3:2003)


183


Progress OpenEdge Driver Data Types Table 11 lists the data types ed by the Progress OpenEdge driver and describes how they are mapped to JDBC data types. Table 11. Progress OpenEdge (OED) Data Types

184

Progress OpenEdge Data Type

JDBC Data Type

bigint

BIGINT

binary

BINARY

bit

BIT

blob

BLOB

char

CHAR

clob

CLOB

date

DATE

decimal

DECIMAL

float

FLOAT

int8

BIGINT

integer

INTEGER

longvarbinary

LONGVARBINARY

longvarchar

LONGVARCHAR

numeric

NUMERIC

real

REAL

smallint

SMALLINT

time

TIME

timestamp

TIMESTAMP

timestamp with time zone

CHAR

tinyint

TINYINT

varbinary

VARBINARY

varchar

VARCHAR


DB2

DB2 The following sections describe settings for the Sonic Database Service DB2 driver: ● “DB2 Driver Connection Properties” ● “DB2 Driver Connection Failover Properties” ● “Specifying Alternate Servers for the DB2 Driver” ● “DB2 Driver Data Types”

DB2 Driver Connection Properties Table 12 describes the JDBC connection properties ed by the DB2 driver. The properties have the format: property=value

Note

All connection property names are case-insensitive. For example, is the same as .

Table 12. DB2 Connection Properties

Property

Description

AddToCreateTable

A string that is appended to the end of all CREATE statements. This property typically is used to add an in database clause.

OPTIONAL AlternateID OPTIONAL

The default schema name that is used to qualify unqualified database objects in dynamically prepared database queries. Valid values depend on your DB2 database: ●

DB2 UDB and DB2 iSeries — Sets the value in the DB2 CURRENT SCHEMA special . 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 .

●

DB2 OS/390 — Sets the value in the DB2 CURRENT SQLID special . The value of this property is validated by the server. Refer to your IBM documentation for valid values for the CURRENT SQLID .


185

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 12. DB2 Connection Properties (continued)

Property

Description

AlternateServers

A list of alternate database servers that the driver will try to connect to if the primary database server is unavailable. The value of this property is a string that specifies each alternate server. This string has the format:

OPTIONAL

(servername1[:port1][;property=value[;...]], servername2[:port2][;property=value[;...]],...)

The server name is required for each alternate server entry. Port number and connection properties (property=value) are optional for each alternate server entry. If the port is unspecified, the port number of the primary server is used. If the port number of the primary server is unspecified, the default port number of 50000 is used. Optional connection properties for the driver are DatabaseName (for DB2 UDB) and LocationName (for DB2 OS/390 and iSeries). For example: jdbc:sonic:db2://server1:50000;DatabaseName=TEST; AlternateServers=(server2:50000;DatabaseName=TEST2, server3:50000;DatabaseName=TEST3)

contains alternate server entries for server2 and server3. The alternate server entries contain the optional DatabaseName property. Other properties are: ●

●

ConnectionRetryCount — Controls the number of times the driver retries the list of servers (primary and alternate) while attempting to establish a connection. ConnectionRetryDelay — Sets the wait interval, in seconds, between

retry attempts. ●

LoadBalancing —

Controls the order in which the driver sequences through the list of servers (primary and alternate) while attempting to establish a connection.

See “Specifying Primary and Alternate Servers” on page 172 for more information about specifying connection information for primary and alternate servers.

186


DB2 Table 12. DB2 Connection Properties (continued)

Property

Description

BatchPerformanceWorkaround OPTIONAL

{true | false}

For DB2 UDB 8.1, the native DB2 batch mechanism is used. This property determines whether certain restrictions are enforced to facilitate data conversions as follows: ●

false —

The methods used to set the parameter values of a batch operation performed using a PreparedStatement must match the database data type of the column the parameter is associated with. This is because DB2 servers do not perform implicit data conversions.

●

true — This restriction is removed; however, parameter sets may not be executed in the order they were specified.

The default is false. CatacludesSynonyms OPTIONAL

{true | false}

This property value determines behavior as follows: ●

true —

Synonyms are included in the result sets returned from the

DatabaseMetaData.getColumns method. ●

false —

Synonyms are omitted from result sets.

The default is true. This property is only applicable for DB2 UDB 7.1 and 7.2, DB2 OS/390, and DB2 iSeries. This property is ignored for DB2 UDB 8.1. The driver always returns synonyms for the DatabaseMetaData.getColumns method when connected to DB2 UDB 8.1. CatalogSchema OPTIONAL

The DB2 schema to use for catalog functions. The value must be the name of a valid DB2 schema. The default is SYSCAT for DB2 UDB, SYSIBM for DB2 OS/390, and QSYS2 for DB2 iSeries. To improve performance, views of system catalog tables can be created in a schema other than the default catalog schema. Setting this property to a schema that contains views of the catalog tables allows the driver to use those views. To ensure that catalog methods function correctly, views for specific catalog tables must exist in the specified schema. The views that are required depend on your DB2 database.


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 ed by your Java Virtual Machine, for example, CharsetFor65535=950. 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 ed by your Java Virtual Machine, for example, CodePageOverride=950. 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



Property

Description


The number of times the driver retries connection attempts to a list of database servers (primary and alternate) until a successful connection is established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry connections if a successful connection is not established on the driver’s first through the list. The default is 0. For example, in the case where the following properties are specified: AlternateServers=(server2:50000,server3:50000,server4:50000)


if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries all the servers in the list only once. If an application sets a timeout value (for example, using DriverManager.Timeout), the timeout takes precedence over this property. For example, if the timeout expires, any connection attempts stop. The ConnectionRetryDelay property specifies the wait interval, in seconds, used between retry attempts. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers.


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)



if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries the list of servers twice. The driver waits 3 seconds between the first connection retry attempt and the second connection retry attempt. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers. CreateDefaultPackage OPTIONAL

{true | false}

This property determines behavior as follows: ●

true — The DB2 driver automatically creates any required DB2 packages.

●

false — The driver creates the required DB2 packages automatically

only if they do not already exist. The default is false. For DB2 UDB, this property must be used in conjunction with the ReplacePackage property.

For DB2 OS/390 and DB2 iSeries, DB2 packages are created in the collection or library specified by the CollectionId property. DatabaseName

The name of the database to which you want to connect. This property is ed only for DB2 UDB.

190



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 Technical 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 . The default is 200.

Grantee OPTIONAL

The name of the schema to which you want to grant EXECUTE privileges for DB2 packages. The value must be a valid DB2 schema. This property is ignored if the GrantExecute property is set to false. The default is PUBLIC.

GrantExecute

{true | false}

OPTIONAL

Determines which DB2 schema is granted EXECUTE privileges for DB2 packages as follows: ●

true — EXECUTE privileges are granted to the schema specified by the Grantee property.

●

false — EXECUTE privileges are granted to the schema that created the DB2 packages.

The default is true.


191


Property

Description

InsensitiveResultSetBufferSize OPTIONAL

{-1 | 0 | x}

Determines the amount of memory used by the driver to cache insensitive result set data as follows: ●

-1 — The driver caches all insensitive result set data in memory. If the

size of the result set exceeds available memory, an OutOfMemoryException is generated. Because the need to write result

set data to disk is eliminated, the driver processes the data more efficiently. ●

0 — The driver caches all insensitive result set data in memory, up to

a maximum of 2 GB. If the size of the result set data exceeds available memory, the driver pages the result set data to disk. Because result set data may be written to disk, the driver may have to reformat the data to write it correctly to disk. ●

where x is a positive integer — The driver caches all insensitive result set data in memory, using this value to set the size (in KB) of the memory buffer for caching insensitive result set data. If the size of the result set data exceeds the buffer size, the driver pages the result set data to disk. Because the result set data may be written to disk, the driver may have to reformat the data to write it correctly to disk. Specifying a buffer size that is a power of 2 results in more efficient memory use. x,

The default is 2048 (KB).

192



Property

Description

LoadBalancing

{true | false}

OPTIONAL

Determines whether the driver will use client load balancing in its attempts to connect to a list of database servers (primary and alternate). The list of alternate servers is specified by the AlternateServers property. The LoadBalancing property determines behavior as follows: ●

true — Client load balancing is used and the driver attempts to connect to the list of database servers (primary and alternate servers) in random order.

●

false —

Client load balancing is not used and the driver connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified).

The default is false. For example, in the case where the following properties are specified: AlternateServers=(server2:50000,server3:50000,server4:50000)


the driver randomly selects from the list of primary and alternate servers which server to connect to first. If that connection fails, the driver again randomly selects from this list of servers until all servers in the list have been tried or a connection is successfully established. See “Client Load Balancing” on page 168 for more information about specifying connection information for primary and alternate servers. LocationName

The name of the DB2 location that you want to access. This property is ed only for DB2 OS/390 and iSeries.


193


Property

Description

MaxPooledStatements OPTIONAL

The maximum number of pooled prepared statements for this connection. MaxPooledStatements property values determine behavior as follows: ●

An integer greater than zero (0) — Enables the DB2 driver’s internal prepared statement pooling, which is useful when the driver is not running from within an application server or another application that provides its own prepared statement pooling. The driver uses this value to cache a certain number of prepared statements created by an application. For example, if the value of this property is set to 20, the driver caches the last 20 prepared statements created by the application.

●

A value greater than the number of prepared statements used by the application — All prepared statements created by the application are cached.

Because CallableStatement is a sub-class of PreparedStatement, are pooled.

CallableStatements also

The default is 0. PackageOwner OPTIONAL

The owner to be used for any DB2 packages that are created.

A case-sensitive used to connect to your DB2 database. A is required only if security is enabled on your database. your system to obtain your .

PortNumber

The T port of the primary database server that is listening for connections to the DB2 database.

OPTIONAL

The default is NULL.

The default is 50000. ReplacePackage

{true | false}

OPTIONAL

Specifies whether the current bind process will replace the existing DB2 packages used by the driver. For DB2 UDB, this property must be used in conjunction with the CreateDefaultPackage property. The default is false.

194



Property

Description

SecurityMechanism

{ClearText | Encrypted | EncryptedUID}

OPTIONAL

Determines the security method the driver uses to authenticate the to the DB2 server when establishing a connection. If the specified authentication method is not ed by the DB2 server, the connection fails and the driver generates an exception. This property determines behavior as follows: ●

ClearText —

The driver sends the in clear text to the DB2 server for authentication.

●

Encrypted — The driver sends an encrypted to the

DB2 server for authentication. ●

EncryptedUID — The driver sends an encrypted ID and to the DB2 server for authentication.

The default is ClearText.


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 ed into the driver is resettable. Sending binary stream data that is less than 32K bytes in length initially as a Blob significantly improves performance if the Insert or Update column is a Blob column.

●

false —

The driver sends binary stream data that is less than 32K to the database as Long Varchar for Bit Data data. If the target column is a Blob column and not a Long Varchar for Bit Data column, the Insert or Update statement fails. The driver retries the Insert or Update statement, sending the data as Blob data.

The default is false. ServerName

196

Specifies either the IP address or the server name (if your network s named servers) of the primary database server. For example, 122.23.15.12 or DB2Server.



Property

Description

StripNewlines OPTIONAL

{true | false}

Specifies whether new-line characters in a database operation are sent to the DB2 server: ●

true — The DB2 driver removes all new-line characters from database operations.

If you know that the database operations used in your application do not contain new-line characters, setting StripNewLines to false eliminates parsing by the DB2 server and improves performance. The default is true.

●

false —

UseCurrentSchema

{true | false}

OPTIONAL

Specifies whether results are restricted to the tables in the current schema if a DatabaseMetaData.getTables call is called without specifying a schema or if the schema is specified as the wildcard character %. Restricting results to the tables in the current schema improves the performance of calls for getTables methods that do not specify a schema. This property determines behavior as follows: ●

true — Results that are returned from the getTables method are restricted to tables in the current schema.

● false — Results of the getTables method are not restricted. The default is false.

The case-sensitive name used to connect to the DB2 database.

WithHoldCursors

{true | false}

OPTIONAL

Determines whether the cursor stays open on commit—either DB2 closes all open cursors (Delete cursors) after a commit or leaves them open (Preserve cursors): ●

true —

The cursor behavior is Preserve.

false — The cursor behavior is Delete. Rolling back a transaction closes all cursors regardless of how this property is specified. The default is true.

●


197


DB2 Driver Connection Failover Properties Table 13 summarizes the connection properties that control how connection failover works with the Database Service DB2 driver. See Table 12 for details about configuring each property. Table 13. Connection Failover Properties for the DB2 Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each server is required. Port number and ed connection properties (DatabaseName or LocationName) are optional. If the port number is unspecified, the port specified for the primary server is used. If a port number is not specified for the primary server, a default port number of 50000 is used.


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


Wait interval, in seconds, used between attempts to connect to a list of database servers (primary and alternate) when the ConnectionRetryCount property is set to a positive integer. The default is 3.

DatabaseName


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


Specifying Alternate Servers for the DB2 Driver The following connection URL for the DB2 driver specifies connection information for the primary and alternate servers: jdbc:sonic:db2://server1:50000;DatabaseName=TEST; AlternateServers=(server2:50000;DatabaseName=TEST2, server3:50000;DatabaseName=TEST3)

198


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)


199


DB2 Driver Data Types Table 14 lists the data types ed by the DB2 driver and describes how they are mapped to JDBC data types. Table 14. DB2 Data Types

DB2 Data Type

JDBC Data Type

Database Comments

Bigint

BIGINT

ed only for DB2 UDB 8.1.

Blob

BLOB

ed only for DB2 UDB 8.1, DB2 OS/390, and DB2 iSeries V5R2.

Char

CHAR

Char for Bit Data

BINARY

Clob

CLOB

Date

DATE

DBClob

CLOB

Decimal

DECIMAL

Double

DOUBLE

Float

FLOAT

Integer

INTEGER

Long Varchar

LONGVARCHAR

Long Varchar for Bit Data

LONGVARBINARY

Numeric

NUMERIC

Real

REAL

Rowid

VARBINARY

Smallint

SMALLINT

Time

TIME

Timestamp

TIMESTAMP

Varchar

VARCHAR

Varchar for Bit Data

VARBINARY

200

ed only for DB2 UDB 8.1, DB2 7.x OS/390, and DB2 iSeries V5R2.

ed only for DB2 OS/390 and DB2 iSeries V5R2.


Informix

Informix The following sections describe settings for the Sonic Database Service Informix driver: ● “Informix Driver Connection Properties” ● “Informix Driver Connection Failover Properties” ● “Specifying Alternate Servers for the Informix Driver” ● “Informix Driver Data Types”

Informix Driver Connection Properties Table 15 describes the JDBC connection properties ed by the Informix driver. The properties have the format: property=value

Note



201


Table 15. Informix Connection Properties

Property

Description

AlternateServers

A comma-separated list of alternate database servers the driver will try to connect to if the primary database server is unavailable. The value of this property is a string that specifies each alternate server. This string has the format:

OPTIONAL


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 ed by your Java Virtual Machine, for example, CodePageOverride=950.


Informix Table 15. Informix Connection Properties (continued)

Property

Description


The number of times the driver retries connections to a list of database servers (primary and alternate) until a successful connection is established. Valid values are 0 and any positive integer.

OPTIONAL

If set to 0, the driver does not retry a connection to the list of database servers if a connection is not established on the driver’s first 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))


if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries all the servers in the list only once. If an application sets a timeout value, the timeout takes precedence over this property. For example, if the timeout expires, any connection attempts to alternate servers stop. If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. The ConnectionRetryDelay property specifies the wait interval, in seconds, used between retry attempts. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers.


203

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 15. Informix Connection Properties (continued)

Property

Description

ConnectionRetryDelay OPTIONAL

The number of seconds the driver will wait between connection retry attempts when ConnectionRetryCount is set to a positive integer. The default is 3. For example, in the case where the following properties are specified: AlternateServers=(server2:2003,server3:2003,server4:2003))



if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries the list of servers twice. It waits 3 seconds between the first connection retry attempt and the second connection retry attempt. NOTE: If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers. DatabaseName

The name of the database to which you want to connect. If this property is not specified, a connection is established to the specified server without connecting to a particular database. A connection that is established to the server without connecting to the database allows an application to use CREATE DATABASE and DROP DATABASE database queries. These statements require that the driver cannot be connected to a database. An application can connect to the database after the connection is established by executing the DATABASE database query. Refer to your IBM Informix documentation for details on using the CREATE and DATABASE database queries.

DATABASE, DROP DATABASE,

204



Property

Description

DBDate

Sets the Informix DBDate server environment variable for formatting literal date values when inserting, updating, and retrieving data in DATE columns. Using this property, you can customize:

OPTIONAL

●

Order in which the month, day, and year fields appear in a date string

●

Year field to contain two or four digits

●

Separator character used to separate the date fields

Valid values are: DMY2

Y4DM

DMY4

Y4MD

MDY2

Y2DM

MDY4

Y4MD

where D is a 2-digit day field, M is a 2-digit month field, Y2 is a 2-digit year field, and Y4 is a 4-digit year field. If unspecified, the format of literal date values conforms to the default server behavior. Optionally, a separator character may be specified as the last character of the value. Valid separator characters are: Hyphen (-) Period (.) Forward slash (/) If a separator is not specified, a forward slash (/) is used to separate the fields. For example, a value of Y4MD- specifies a date format that has a 4digit year, followed by the month and then by the day. The date fields are separated by a hyphen (-). For example: 2004-02-15. This property does not affect the format of the string in the date escape syntax. Dates specified using the date escape syntax always use the JDBC escape format yyyy-mm-dd.


205


Property

Description

DiagnosticFilename OPTIONAL


InformixServer

The name of the Informix database server to which you want to connect.

InsensitiveResultSetBufferSize

{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive result set data: ●

-1 — The driver caches all insensitive result set data in memory. If the

size of the result set exceeds available memory, an OutOfMemoryException is generated. Because the need to write result

set data to disk is eliminated, the driver processes the data more efficiently. ●



x, where x is a positive integer — The driver caches all insensitive result set data in memory, using this value to set the size (in KB) of the memory buffer for caching insensitive result set data. If the size of the result set data exceeds the buffer size, the driver pages the result set data to disk. Because the result set data may be written to disk, the driver may have to reformat the data to write it correctly to disk. Specifying a buffer size that is a power of 2 results in more efficient memory use.

The default is 2048 (KB)

206



Property

Description

LoadBalancing

{true | false}

OPTIONAL


true — The driver uses client load balancing and attempts to connect to the database servers (primary and alternate servers) in random order.

●

false —

Client load balancing is not used and the driver connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified).

The default is false. For example, in the case where the following properties are specified: AlternateServers=(server2:2003,server3:2003;server4:2003)


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.


207


Property

Description

MaxPooledStatements

The maximum number of pooled prepared statements for this connection. MaxPooledStatements property values determine behavior as follows:

OPTIONAL

●

An integer greater than zero (0) — Enables the Informix driver’s 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.

●




The default is 0.

A case-insensitive used to connect to your Informix database. A is required only if security is enabled on your database. If so, your system to obtain your .

The case-insensitive default name used to connect to the Informix database. A name is required only if security is enabled on your database. If so, your system to obtain your name.

208


Informix

Informix Driver Connection Failover Properties Table 16 summarizes the connection properties that control how connection failover works with the Database Service DB2 driver. See Table 15 for details about configuring each property. Table 16. Connection Failover Properties for the Informix Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each server is required. Port number and ed connection properties (DatabaseName or InformixServer) are optional. If the port number is unspecified, the port specified for the primary server is used. If a port number is not specified for the primary server, the port specified for the primary server is used.





DatabaseName


InformixServer

The name of the Informix database server to which you want to connect.

LoadBalancing



Specifying Alternate Servers for the Informix Driver The following connection URL for the Informix driver specifies connection information for the primary and alternate servers: jdbc:sonic:informix://server1:2003;InformixServer=TestServer; DatabaseName=TestServer; AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)


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)

Informix Driver Data Types Table 17 lists the data types ed by the Informix driver and describes how they are mapped to JDBC data types. Table 17. Informix Data Types

210

Informix Data Type

JDBC Data Type

blob

BLOB

boolean

BIT

byte

LONGVARBINARY


Informix Table 17. Informix Data Types (continued)

Informix Data Type

JDBC Data Type

clob

CLOB

char

CHAR

date

DATE

datetime hour to second

TIME

datetime year to day

DATE

datetime year to fraction(5)

TIMESTAMP

datetime year to second

TIMESTAMP

decimal

DECIMAL

float

FLOAT

int8

BIGINT

integer

INTEGER

lvarchar

VARCHAR

money

DECIMAL

nchar

CHAR

nvarchar

VARCHAR

serial

INTEGER

serial8

BIGINT

smallfloat

REAL

smallint

SMALLINT

text

LONGVARCHAR

varchar

VARCHAR


211


Oracle The following sections describe settings for the Sonic Database Service Oracle driver: ● “Oracle Driver Connection Properties” ● “Oracle Driver Connection Failover Properties” ● “Specifying Alternate Servers for the Oracle Driver” ● “Oracle Driver Data Types”

Oracle Driver Connection Properties Table 18 describes the JDBC connection properties ed by the Oracle driver. The properties have the format: property=value

Note

212



Oracle Table 18. Connection Properties for the Oracle Driver

Property

Description

AlternateServers


OPTIONAL


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 —


If using a tnsnames.ora file to retrieve connection information, do not specify this property. See “Specifying Primary and Alternate Servers” on page 172 for more information about specifying connection information for primary and alternate servers.


213

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description

BatchPerformanceWorkaround

{true | false}

OPTIONAL

Determines the method used to execute batch operations: ●

true — The native Oracle batch mechanism is used. The native Oracle batch mechanism does not return individual update counts for each statement or parameter set in the batch. For this reason, the driver returns a value of SUCCESS_NO_INFO (-2) for each entry in the returned update count array.

●

false —

The JDBC 3.0-compliant batch mechanism is used. If an application can accept not receiving update count information, setting this property to true can significantly improve performance.

The default is false. CatacludesSynonyms DEPRECATED

This property is recognized for compatibility with existing data sources, but we recommend that you use the CatalogOptions property instead to include synonyms in result sets.

CatalogOptions

{0 | 1 | 2 | 3}

OPTIONAL

Determines the type of information included in result sets returned from catalog functions: ●

0—

Result sets contain default DatabaseMetaData results.

●

1—

Result sets contain Remarks information returned from the

DatabaseMetaData methods: getTables and getColumns. ●

2—

Result sets contain synonyms returned from the

DatabaseMetaData methods: getColumns, getProcedures, getProcedureColumns, ●

and getIndexInfo.

3 — Result sets contain remarks and synonyms (as described in options 1 and 2).

The default is 2.

214


Oracle Table 18. Connection Properties for the Oracle Driver (continued)

Property

Description



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 driver’s first 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)


if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries all the servers in the list only once. If an application sets a timeout value (for example, using DriverManager.Timeout), the timeout takes precedence over this property. For example, if the timeout expires, any connection attempts to alternate servers stop. If the LoadBalancing property also is specified, the driver may sequence through the list of servers (primary and alternate) in a different order each time. The ConnectionRetryDelay property specifies the wait interval, in seconds, used between attempts. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers.


215


Property

Description


The number of seconds the driver waits before retrying connections to a list of database servers (primary and alternate) when ConnectionRetryCount is set to a positive integer.

OPTIONAL

The default is 3. For example, in the case where the following properties are specified: AlternateServers=(server2:1521,server3:1521,server4:1521)



if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries the list of servers twice. The driver waits 3 seconds between the first connection retry attempt and the second connection retry attempt. If the LoadBalancing property also is specified, the driver may sequence through the list of servers (primary and alternate) in a different order each time. The ConnectionRetryCount property specifies the number of times the driver will attempt to connect to all the servers in the list of alternate servers. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers. DiagnosticFilename OPTIONAL


216



Property

Description

FetchTSWTZasTimestamp

{true | false}

OPTIONAL

This property determines behavior as follows: ●

true —

Allows column values with the TIMESTAMP WITH TIME ZONE data type (Oracle9i or higher) to be retrieved as a JDBC TIMESTAMP data type.

●

false — Column values with the TIMESTAMP type must be retrieved as a string.

WITH TIME ZONE data

The default is false. InsensitiveResultSetBufferSize

{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive result set data: ●

— The driver caches all insensitive result set data in memory. If the size of the result set exceeds available memory, an OutOfMemoryException is generated. Because the need to write result set data to disk is eliminated, the driver processes the data more efficiently.

●


-1





217


Property

Description

LoadBalancing

{true | false}

OPTIONAL



●

false — Client load balancing is not used and the driver connects to

each server based on their sequential order (primary server first, then, alternate servers in the order they are specified). The default is false. For example, in the case where the following properties are specified: AlternateServers=(server2:1521,server3:1521,server4:1521)


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



Property

Description

MaxPooledStatements


OPTIONAL

●

An integer greater than zero (0) — Enables the Oracle driver’s 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.

●




The default is 0.

A case-insensitive used to connect to your Oracle database. A is required only if security is enabled on your database. If so, your system to obtain your .


219


Property

Description

ServerType

{Shared | Dedicated}

OPTIONAL

Specifies whether the connection is established using a shared or dedicated server process (UNIX) or thread (Windows): ●

Shared — The server process to be used is retrieved from a pool. The

socket connection between the client and server is made to a dispatcher process on the server. This setting allows there to be fewer processes than the number of connections, reducing the need for server resources. Use this value when a server must handle many s with fewer server resources. ●

Dedicated —

A server process is created to service only that connection. When that connection ends, so does the process (UNIX) or thread (Windows). The socket connection is made directly between the application and the dedicated server process or thread. When connecting to UNIX servers, a dedicated server process can provide significant performance improvement, but uses more resources on the server. When connecting to Windows servers, the server resource penalty is insignificant. Use this value if you have a batch environment with low numbers of s.

●

Unspecified — The driver uses the server type set on the server.

If using a tnsnames.ora file to provide connection information, do not specify this property. ServiceName OPTIONAL

The database service name that specifies the database used for the connection. The service name is a string that is the global database name—a name that typically comprises the database name and domain name. For example: sales.us.acme.com

This property is useful to specify connections to an Oracle Real Application Clusters (RAC) system rather than a specific Oracle instance because the nodes in a RAC system share a common service name. If using a tnsnames.ora file to provide connection information, do not specify this property.

220



Property

Description

SID

The Oracle System Identifier that refers to the instance of the Oracle database running on the server. This property is mutually exclusive with the ServiceName property.

OPTIONAL

The default is ORCL, which is the default SID that is configured when installing your Oracle database. If using a tnsnames.ora file to provide connection information, do not specify this property. TNSNamesFile OPTIONAL

The path and filename to the tnsnames.ora file from which connection information is retrieved. The tnsnames.ora file contains connection information that is mapped to Oracle net service names. Using a tnsnames.ora file to centralize connection information simplifies maintenance when changes occur. The value of this property must be a valid path and filename to a tnsnames.ora file. If you specify this property, you also must specify the TNSServerName property. If this property is specified, do not specify the following properties to prevent connection information conflicts: ●

AlternateServers

●

LoadBalancing

●

PortNumber

●

ServerName

●

ServerType

●

ServiceName

●

SID

If any of these properties are specified in addition to this property, the driver generates an exception.


221


Property

Description

TNSServerName

The Oracle net service name used to reference the connection information in a tnsnames.ora file. The value of this property must be a valid net service name entry in the tnsnames.ora file specified by the TNSNamesFile property.

OPTIONAL

If this property is specified, you also must specify the TNSNamesFile property. If this property is specified, do not specify the following properties to prevent connection information conflicts: ●

AlternateServers

●

LoadBalancing

●

PortNumber

●

ServerName

●

ServerType

●

ServiceName

●

SID

If any of these properties are specified in addition to this property, the driver generates an exception.

222

The case-insensitive default name used to connect to your Oracle database. A name is required only if security is enabled on your database. If so, your system to obtain your name. Operating System authentication is not currently ed by the Oracle driver.


Oracle

Oracle Driver Connection Failover Properties Table 19 summarizes the connection properties that control how connection failover works with the Oracle driver. See Table 18 for details about configuring each property. Table 19. Connection Failover Properties for the Oracle Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each server is required. Port number and the ServiceName or SID connection properties are optional. If the port number is unspecified, the port specified for the primary server is used. If a port number is not specified for the primary server, the default port number of 1521 is used.





LoadBalancing


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.



223


Specifying Alternate Servers for the Oracle Driver The following connection URL for the Oracle driver specifies connection information for the primary and alternate servers: jdbc:sonic:oracle://server1:1521;ServiceName=TEST; AlternateServers=(server2:1521;ServiceName=TEST2,server3:1521; ServiceName=TEST3)

In this example: ...server1:1521;ServiceName=TEST...

is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property, in this example: ...;AlternateServers=(server2:1521;ServiceName=TEST2, server3:50000;ServiceName=TEST3)

You can specify the optional connection properties ServiceName or SID for each alternate server entry. These properties are mutually exclusive. For example: jdbc:sonic:oracle://server1:1521;ServiceName=TEST; AlternateServers=(server2:1521;ServiceName=TEST2,server3:1521)

or jdbc:sonic:oracle://server1:1521;SID=ORCL; AlternateServers=(server2:1521;SID=ORCL2,server3:1521)

If you do not specify an optional connection property in an alternate server entry, the connection to that alternate server uses the property specified in the URL for the primary server. For example, if you specify SID=ORCL for the primary server, but do not specify a SID in the alternate server entry as shown in the following URL, the driver uses the SID specified for the primary server and tries to connect to the ORCL database on the alternate server: jdbc:sonic:oracle://server1:1521;SID=ORCL; AlternateServers=(server2:1521,server3:1521)

224


Oracle

Oracle Driver Data Types The following sections list data types ed by the Oracle driver, and describe the XMLType data type ed by Oracle9i and higher drivers.

Oracle Data Types Table 20 lists the data types ed by the Oracle driver and describes how they are mapped to JDBC data types. Table 20. Oracle Data Types

Oracle Database

Oracle Data Type

JDBC Data Type

Oracle8i and higher

BFILE

BLOB

BLOB

BLOB

CHAR

CHAR

CLOB

CLOB

DATE

TIMESTAMP

FLOAT(n)

DOUBLE

LONG

LONGVARCHAR

long raw

LONGVARBINARY

NCHAR

CHAR

NCLOB

CLOB

NUMBER (p, s)

DECIMAL

NUMBER

DOUBLE

NVARCHAR2

VARCHAR

TIMESTAMP

TIMESTAMP

TIMESTAMP WITH LOCAL TIME ZONE

TIMESTAMP

TIMESTAMP WITH TIME ZONE

VARCHAR

VARCHAR2

VARCHAR

XMLType

CLOB

Oracle9i and higher


225

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 20. Oracle Data Types (continued)

Oracle Database

Oracle Data Type

JDBC Data Type

Oracle10g only

BINARY_FLOAT

REAL

BINARY_DOUBLE

DOUBLE

XMLType Data Type The Oracle driver s tables containing columns specified as XMLType for Oracle9i and higher. The driver maps the Oracle XMLType data type to the JDBC CLOB data type. XMLType columns can be used in queries just like any other column type. The data from XMLType columns can be retrieved as a String, Clob, CharacterStream, or AsciiStream. When inserting or updating XMLType columns, the data to be inserted or updated must be in the form of an XMLType data type. Oracle provides the xmltype() function to construct an XMLType data object. The xmlData argument of the xmltype() function can be specified as a string literal or a parameter marker. If a parameter marker is used, the parameter value may be set using the setString, setClob, setCharacterStream, or setAsciiStream methods. The following code inserts data into an XMLType column using a statement with a string literal as the xmlData argument of the xmltype() function: // Insert xml data as a literal String sql = "insert into XMLTypeTbl values (1, xmltype('" + "<emp><empNo>123<empName>Mark'))"; Statement stmt = con.createStatement(); stmt.executeUpdate(sql);

The following code inserts data into an XMLType column using a prepared statement: //

Insert xml data as a String parameter

String xmlStr = "<emp><empNo>234<empName>Trish"; String sql = "insert into XMLTypeTbl values (?, xmltype(?))"; PreparedStatement prepStmt = con.prepareStatement(sql); prepStmt.setInt(1, 2); prepStmt.setString(2, xmlStr); prepStmt.executeUpdate();

226



When the data from an XMLType column is retrieved as a Clob, the XMLType data cannot be updated using the Clob object. Calling the setString, setCharacterStream, or setAsciiStream methods of a Clob object returned from an XMLType column generates an SQLException.

Microsoft SQL Server The following sections describe settings for the Sonic Database Service Microsoft SQL Server driver: ● “Microsoft SQL Server Driver Connection Properties” ● “Microsoft SQL Server Driver Connection Failover Properties” ● “Specifying Alternate Servers for the Microsoft SQL Server Driver” ● “Microsoft SQL Server Driver Data Types”

Microsoft SQL Server Driver Connection Properties Table 21 describes the JDBC connection properties ed by the Microsoft SQL Server driver. The properties have the format: property=value

Note



227

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 21. Connection Properties for the Microsoft SQL Server Driver

Property

Description

AlternateServers


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)


●

— Controls the number of times the driver retries the list of servers (primary and alternate) while attempting to establish a connection.


ConnectionRetryDelay — Sets the wait interval, in seconds, between

retry attempts. ●

LoadBalancing —


See “Specifying Primary and Alternate Servers” on page 172 or more information about specifying connection information for primary and alternate servers.

228


Microsoft SQL Server Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description

AlwaysReportTriggerResults

{true | false}

OPTIONAL

Determines how the driver reports results generated by database triggers (procedures that are stored in the database and executed, or fired, when a table is modified): ●

true — The driver returns all results, including results generated by triggers. Multiple trigger results are returned one at a time. Use the Statement.getMoreResults method to retrieve individual trigger results. Warnings and errors are reported in the results as they are encountered.

●

false — The driver does not report trigger results if the statement is

a single Insert, Update, or Delete statement. In this case, the only result that is returned is the update count generated by the statement that was executed (if errors do not occur). Although trigger results are ignored, any errors generated by the trigger are reported. Any warnings generated by the trigger are enqueued. If errors are reported, the update count is not reported. The default is false. CodePageOverride OPTIONAL

Specifies the code page the driver uses when converting character data. The specified code page overrides the default database code page. All character data retrieved from or written to the database is converted using the specified code page. The value must be a string containing the name of a valid code page ed by your Java Virtual Machine, for example, CodePageOverride=950. 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.


229

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)

Property

Description



OPTIONAL



if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries all the servers in the list only once. If an application sets a timeout value, the timeout takes precedence over this property. For example, if the timeout expires, any connection attempts to alternate servers stop. If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. The ConnectionRetryDelay property specifies the wait interval, in seconds, used between attempts. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers.

230



Property

Description


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




if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries the list of servers twice. It waits 3 seconds between the first connection retry attempt and the second connection retry attempt. NOTE: If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers. DatabaseName


OPTIONAL DiagnosticFilename OPTIONAL


HostProcess OPTIONAL

The process ID of the application connecting to Microsoft SQL Server. The value of this property appears in the hostprocess column of the master.dbo.sysprocesses table and may be useful for database istration purposes. The default is 0.


231


Property

Description


{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive result set data. This property must have one of the following values: ●


●


-1




232



Property

Description

LoadBalancing

{true | false}

OPTIONAL



●






233


Property

Description

MaxPooledStatements


OPTIONAL

●

An integer greater than zero (0) — Enables the SQL Server driver’s 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.

●




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 istration purposes. The default is 000000000000.

OPTIONAL

A case-insensitive used to connect to your Microsoft SQL Server database. If a name is not specified, the driver will use Windows authentication when connecting to Microsoft SQL Server. In this case, a is not required. If a is required, your system to obtain your . Refer to the Progress Sonic ESB Product Family: Installation and Upgrade Guide for product requirements and configuration that must be met to use Windows authentication with the SQL Server driver.

ProgramName OPTIONAL

The name of the application connecting to Microsoft SQL Server. The value of this property appears in the program_name column of the master.dbo.sysprocesses table and is useful for database istration purposes. The default is an empty string.

234



Property

Description

SelectMethod

{direct | cursor}

OPTIONAL

A hint to the driver that determines whether the driver requests a database cursor for Select statements. Performance and behavior of the driver are affected by this property, which is defined as a hint because the driver might not always be able to satisfy the requested method. ●

Direct —

When the driver uses the Direct method, the database server sends the complete result set in a single response to the driver when responding to a query. A server-side database cursor is not created. Typically, responses are not cached by the driver. Using this method, the driver must process all the response to a query before another query is submitted. If another query is submitted (using a different statement on the same connection, for example), the driver caches the response to the first query before submitting the second query. Typically, the Direct method performs better than the Cursor method.

●

Cursor —

When the driver uses the Cursor method, a server-side cursor is requested. The rows are retrieved from the server in blocks when returning forward-only result sets. The JDBC Statement method setFetchSize can be used to control the number of rows that are retrieved for each request. Performance tests show that the value of setFetchSize significantly impacts performance when the Cursor method is used. There is no simple rule for determining the setFetchSize value that you should use. We recommend that you experiment with different setFetchSize values to determine which value gives the best performance for your application. The Cursor method is useful for queries that produce a large amount of data, particularly if multiple open result sets are used.

The default is Direct.


235


Property

Description

SendStringParametersAsUnicode

{true | false}

OPTIONAL

Determines whether string parameters are sent to the Microsoft SQL Server database in Unicode or in the default character encoding of the database: ●

true — String parameters are sent to Microsoft SQL Server in Unicode.

●

false —

String parameters are sent in the default encoding, which can improve performance because the server does not need to convert Unicode characters to the default encoding. You should, however, use default encoding only if the parameter string data you specify is the same as the default encoding of the database.

The default is true. If a value is specified for the CodePageOverride property and this property is set to true, this property is ignored and a warning is generated.

The case-insensitive name used to connect to your Microsoft SQL Server database. If a name is not specified, the driver uses Windows authentication when connecting to the database server. In this case, a name is not required. If a name is required, your system to obtain your name.

OPTIONAL

Refer to the Progress Sonic ESB Product Family: Installation and Upgrade Guide for product and configuration requirements that must be met to use Windows authentication with the SQL Server driver. UseServerSideUpdatableCursors

{true | false}

Determines whether the driver uses server-side cursors when an updatable result set is requested: ●

true — Server-side updatable cursors are created when an updatable result set is requested.

●

false —

The default updatable result set functionality is used.

The default is false.

236



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

OPTIONAL

The default is an empty string. XATransactionGroup OPTIONAL

The transaction group ID that identifies any transactions initiated by the connection. This ID can be used for distributed transaction cleanup purposes. You can use the XAResource.recover method to roll back any transactions left in an unprepared state. When you call XAResource.recover, any transactions that match the ID on the connection used to call XAResource.recover are rolled back. For example, if you specify XATransactionGroup=ACCT200 and call XAResource.recover on the same connection, any transactions left in an unprepared state identified by the transaction group ID of ACCT200 are rolled back.


237


Microsoft SQL Server Driver Connection Failover Properties Table 22 summarizes the connection properties that control how connection failover works with the Database Service SQL Server driver. See Table 21 for details about configuring each property. Table 22. Connection Failover Properties for the Microsoft SQL Server Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each server is required. Port number and ed connection properties (DatabaseName) are optional. If the port number is unspecified, the port number specified for the primary server is used. If a port number is unspecified for the primary server, the default port number of 1433 is used.





DatabaseName


LoadBalancing



Specifying Alternate Servers for the Microsoft SQL Server Driver The following connection URL for the Microsoft SQL Server driver specifies connection information for the primary and alternate servers: jjdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST; AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433; DatabaseName=TEST3)

In this example: 238


Microsoft SQL Server ....server1:1433;DatabaseName=TEST...

is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property, in this example: ...;AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433; DatabaseName=TEST3)

You can specify an optional instance property for each alternate server entry. For example: jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST; AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433; DatabaseName=TEST3)

or, if connecting to named instances: jdbc:sonic:sqlserver://server1\\instance1:1433;DatabaseName=TEST; AlternateServers=(server2\\instance2:1433;DatabaseName=TEST2,s erver3\\instance3:1433;DatabaseName=TEST3)

If you do not specify an optional connection property in an alternate server entry, the connection to that alternate server uses the property specified in the URL for the primary server. For example, if you specify DatabaseName=TestServer for the primary server, but do not specify the InformixServer and DatabaseName properties in the alternate server entry as shown in the following URL, the driver uses the InformixServer and DatabaseName specified for the primary server and tries to connect to the TEST database on the alternate server: jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST; AlternateServers=(server2:1433,server3:1433)

The SQL Server driver also allows you to specify connections to named instances, multiple instances of a Microsoft SQL Server database running concurrently on the same server. If specifying named instances for the primary and alternate servers, the connection URL would look like this: jdbc:datadirect:sqlserver://server1\\instance1; AlternateServers=(server2\\instance2:1433;DatabaseName=TEST2, server3\\instance3:1433;DatabaseName=TEST3)


239


Microsoft SQL Server Driver Data Types Table 23 lists the data types ed by the Microsoft SQL Server driver and describes how they are mapped to JDBC data types. These data types are for SQL Server 7 and 2000 unless otherwise noted in the table. Table 23. Microsoft SQL Server Driver Data Types

240

Microsoft SQL Server DataBase

Microsoft SQL Server Data Type

JDBC Data Type

SQL Server 7 and 2000

binary

BINARY

bit

BIT

char

CHAR

datetime

TIMESTAMP

decimal

DECIMAL

decimal() identity

DECIMAL

float

FLOAT

image

LONGVARBINARY

int

INTEGER

int identity

INTEGER

money

DECIMAL

nchar

CHAR

ntext

LONGVARCHAR

numeric

NUMERIC

numeric() identity

NUMERIC

nvarchar

VARCHAR

real

REAL

smalldatetime

TIMESTAMP

smallint

SMALLINT


Microsoft SQL Server Table 23. Microsoft SQL Server Driver Data Types (continued)

Microsoft SQL Server DataBase

Microsoft SQL Server Data Type

JDBC Data Type

SQL Server 7 and 2000

smallint identity

SMALLINT

smallmoney

DECIMAL

sysname

VARCHAR

text

LONGVARCHAR

timestamp

BINARY

tinyint

TINYINT

tinyint identity

TINYINT

uniqueidentifier

CHAR

varbinary

VARBINARY

varchar

VARCHAR

bigint

BIGINT

bigint identity

BIGINT

sql_variant

VARCHAR

SQL Server 2000 only


241


Sybase The following sections describe settings for the Sonic Database Service Sybase driver: ● “Sybase Driver Connection Properties” ● “Sybase Driver Connection Failover Properties” ● “Specifying Alternate Servers for the Sybase Driver” ● “Sybase Driver Data Types”

Sybase Driver Connection Properties Table 24 describes the JDBC connection properties ed by the Sybase driver. The properties have the format: property=value

Note

242



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)


●


retry attempts. ●

LoadBalancing —


See “Specifying Primary and Alternate Servers” on page 172 for more information about specifying connection information for primary and alternate servers


243

Chapter 9: Driver Connection Properties and Data Types by Database Brand Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description

BatchPerformanceWorkaround

{true | false}

OPTIONAL

Determines the method used to execute batch operations: — The native Sybase batch mechanism is used.

●

true

●

false —

The JDBC 3.0-compliant batch mechanism is used.

In most cases, using the native Sybase batch functionality provides significantly better performance, but the driver may not always be able to return update counts for the batch. The default is false. CodePageOverride OPTIONAL

244

Specifies the code page the driver uses when converting character data. The specified code page overrides the default database code page. All character data retrieved from or written to the database is converted using the specified code page. The value must be a string containing the name of a valid code page ed by your Java Virtual Machine, for example, CodePageOverride=950.


Sybase Table 24. Connection Properties for the Sybase Driver (continued)

Property

Description



OPTIONAL



if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries all the servers in the list only once. If an application sets a timeout value, the timeout takes precedence over this property. For example, if the timeout expires, any connection attempts to alternate servers stop. If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. The ConnectionRetryDelay property specifies the wait interval, in seconds, used between attempts. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers.


245


Property

Description


The number of seconds the driver waits before retrying connections to a list of database servers (primary and alternate) when ConnectionRetryCount is set to a positive integer.

OPTIONAL




if a connection is not successfully established on the driver’s first through the list of database servers, the driver retries the list of servers twice. It waits 3 seconds between the first connection retry attempt and the second connection retry attempt. If the LoadBalancing property is set to true, the driver may sequence through the list of servers (primary and alternate) in a different order each time. See “Connection Retry” on page 170 for more information about specifying connection information for primary and alternate servers. DatabaseName


OPTIONAL DiagnosticFilename OPTIONAL


246



Property

Description


{-1 | 0 | x}

OPTIONAL

Determines the amount of memory used by the driver to cache insensitive result set data. It must have one of the following values: ●


●


-1





247


Property

Description

LoadBalancing

{true | false}

OPTIONAL



●





248



Property

Description

MaxPooledStatements


OPTIONAL

●

An integer greater than zero (0) — Enables the Sybase driver’s 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.

●




The default is 0.

The case-sensitive used to connect to your Sybase database. A is required only if security is enabled on your database. If so, your system to get your .


249


Property

Description

PrepareMethod

{StoredProc | StoredProclfParam | Direct}

OPTIONAL

Determines whether stored procedures are created on the server for prepared statements: ●

StoredProc —

A stored procedure is created when the statement is prepared and is executed when the prepared statement is executed.

●

StoredProcIfParam —

●

Direct —

A stored procedure is created only if the prepared statement contains one or multiple parameter markers. In this case, it is created when the statement is prepared and is executed when the prepared statement is executed. If the statement does not contain parameter markers, a stored procedure is not created and the statement is executed directly. A stored procedure is not created for the prepared statement and the statement is executed directly. A stored procedure might be created if parameter metadata is requested.

The default is StoredProclfParam. Setting this property to StoredProc or StoredProclfParam can improve performance if your application executes prepared statements multiple times because, once created, executing a stored procedure is faster than executing a single database query. If a prepared statement is only executed once or is never executed, performance can decrease because creating a stored procedure incurs more overhead on the server than simply executing a single database query. Setting this property to Direct should be used if your application does not execute prepared statements multiple times.

250



Property

Description

SelectMethod

{Direct | Cursor}

OPTIONAL

A hint to the driver that determines whether the driver requests a database cursor for Select statements. Performance and behavior of the driver are affected by this property, which is defined as a hint because the driver may not always be able to satisfy the requested method. — When the driver uses the Direct method, the database server sends the complete result set in a single response to the driver when responding to a query. A server-side database cursor is not created. Typically, responses are not cached by the driver. Using this method, the driver must process all the response to a query before another query is submitted. If another query is submitted (using a different statement on the same connection, for example), the driver caches the response to the first query before submitting the second query. Typically, the Direct method performs better than the Cursor method.

●

Direct

●

Cursor —

When the driver uses the Cursor method, a server-side database cursor is requested. The rows are retrieved from the server in blocks when returning forward-only result sets. The JDBC Statement method setFetchSize can be used to control the number of rows that are retrieved for each request. Performance tests show that the value of setFetchSize significantly impacts performance when the Cursor method is used. There is no simple rule for determining the setFetchSize value that you should use. We recommend that you experiment with different setFetchSize values to find out which value gives the best performance for your application. The Cursor method is useful for queries that produce a large amount of data, particularly if multiple open result sets are used.

The default is Direct.

The case-insensitive name used to connect to your Sybase database. A name is required only if security is enabled on your database. If so, your system to get your name.


251


Sybase Driver Connection Failover Properties Table 25 summarizes the connection properties that control how connection failover works with the Database Service Sybase driver. See Table 24 for details about configuring each property. Table 25. Connection Failover Properties for the Sybase Driver

Property

Description

AlternateServers

List of alternate database servers. An IP address or server name identifying each server is required. Port number and the DatabaseName connection property are optional. If the port number is unspecified, the port number specified for the primary server is used. If a port number is unspecified for the primary server, the port number specified for the primary server is used.





DatabaseName


LoadBalancing



Specifying Alternate Servers for the Sybase Driver The following connection URL for the Sybase driver specifies connection information for the primary and alternate servers: jdbc:sonic:sybase://server1:4100;DatabaseName=TEST; AlternateServers=(server2:4100;DatabaseName=TEST2,server3:4100; DatabaseName=TEST3)

252


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)


253


Sybase Driver Data Types Table 26 lists the data types ed by the Sybase driver and describes how they are mapped to JDBC data types. Table 26. Sybase Driver Data Types

254

Sybase DataBase

Sybase Data Type

JDBC Data Type

Sybase 11.5 and higher

binary

BINARY

bit

BIT

char

CHAR

datetime

TIMESTAMP

decimal

DECIMAL

decimal() identity

DECIMAL

float

FLOAT

image

LONGVARBINARY

int

INTEGER

money

DECIMAL

nchar

CHAR

numeric

NUMERIC

nvarchar

VARCHAR

real

REAL

smalldatetime

TIMESTAMP

smallint

SMALLINT

smallmoney

DECIMAL

sysname

VARCHAR

text

LONGVARCHAR

timestamp

VARBINARY

tinyint

TINYINT

varbinary

VARBINARY

varchar

VARCHAR


Sybase Table 26. Sybase Driver Data Types (continued)

Sybase DataBase

Sybase Data Type

JDBC Data Type

Sybase 12.5 and 12.5.1 only

date

DATE

time

TIME

unichar

CHAR

univarchar

VARCHAR

Note For s of Adaptive Server 12.5 and 12.5.1: The Sybase driver s extended new

limits (XNL) for character and binary columns—columns with lengths greater than 255. Refer to your Sybase documentation for more information about XNL for character and binary columns.


255


256


Chapter 10

SQL Escape Sequences for JDBC

Language features, such as outer s and scalar function calls, are commonly implemented by database systems. The syntax for these features is often databasespecific, even when a standard syntax has been defined. This chappter describes the JDBC-defined escape sequences containing standard syntaxes for the following language features: ● “Date, Time, and Timestamp Escape Sequences” ● “Scalar Functions” ● “Outer Escape Sequences” ● “Procedure Call Escape Sequences” The escape sequence used by JDBC is: {extension}

The escape sequence is recognized and parsed by Progress Sonic Database Service JDBC drivers, and replaces the escape sequences with data store-specific grammar.


257

Chapter 10: SQL Escape Sequences for JDBC

Date, Time, and Timestamp Escape Sequences The escape sequence for date, time, and timestamp literals is: {literal-type 'value'}

where literal-type is one of the following: literal-type

Description

Value Format

d

Date

yyyy-mm-dd

t

Time

h:mm:ss [1]

ts

Timestamp

yyyy-mm-dd hh:mm:ss[.f...]

For example: UPDATE Orders SET OpenDate={d '1995-01-15'} WHERE OrderID=1023

Scalar Functions You can use scalar functions in database queries with the following syntax: {fn scalar-function}

where scalar-function is a scalar function ed by Database Service JDBC drivers, as listed in Table 27. For example: SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}

258


Scalar Functions Table 27. Scalar Functions ed by Database Service JDBC Drivers

Data Store

String Functions

Numeric Functions

Timedate Functions

System Functions

Progress OpenEdge

CONCAT

ABS

CURRDATE

DATABASE

LEFT

ACOS

CURRTIME

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


259

Chapter 10: SQL Escape Sequences for JDBC Table 27. Scalar Functions ed by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric Functions

Timedate Functions

System Functions

DB2

ASCII

ABS or ABSVAL

DATE

COALESCE

BLOB

ACOS

DAY

DEREF

CHAR

ASIN

DAYNAME

DLCOMMENT

CHR

ATAN

DAYOFWEEK

DLLINKTYPE

CLOB

ATANH

DAYOFYEAR

DLURLCOMPLETE

CONCAT

ATAN2

DAYS

DLURLPATH

DBCLOB

BIGINT

HOUR

DLURLPATHONLY

DIFFERENCE

CEILING or CEIL

JULIAN_DAY

DLURLSCHEME

GRAPHIC

COS

MICROSECOND

DLURLSERVER

HEX

COSH

MIDNIGHT_SECONDS

DLVALUE

INSERT

COT

MINUTE

EVENT_MON_STATE

LCASE or LOWER

DECIMAL

MONTH

GENERATE_UNIQUE

LCASE (SYSFUN schema)

DEGREES

MONTHNAME

NODENUMBER

LEFT

DIGITS

QUARTER

NULLIF

LENGTH

DOUBLE

SECOND

PARTITION

LOCATE

EXP

TIME

RAISE_ERROR

LONG_VARCHAR

FLOAT

TIMESTAMP

TABLE_NAME

LONG_VARGRAPHIC

FLOOR

TIMESTAMP_ISO

TABLE_SCHEMA

LTRIM

INTEGER

TIMESTAMPDIFF

TRANSLATE

LTRIM (SYSFUN schema)

LN

WEEK

TYPE_ID

POSSTR

LOG

YEAR

TYPE_NAME

REPEAT

LOG10

TYPE_SCHEMA

REPLACE

MOD

VALUE

RIGHT

POWER

RTRIM

RADIANS

RTRIM (SYSFUN schema)

RAND

SOUNDEX

REAL

SPACE

ROUND

SUBSTR

SIGN

TRUNCATE or TRUNC

SIN

UCASE or UPPER

SINH

VARCHAR

SMALLINT

VARGRAPHIC

SQRT TAN TANH TRUNCATE

260


Scalar Functions Table 27. Scalar Functions ed by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric Functions

Timedate Functions

System Functions

Informix

CONCAT

ABS

CURDATE

DATABASE

LEFT

ACOS

CURTIME

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


261


Data Store

String Functions

Numeric Functions

Timedate Functions

System Functions

Oracle

ASCII

ABS

CURDATE

IFNULL

BIT_LENGTH

ACOS

DAYNAME

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


Scalar Functions Table 27. Scalar Functions ed by Database Service JDBC Drivers (continued)

Data Store

String Functions

Numeric Functions

Timedate Functions

System Functions


ASCII

ABS

DAYNAME

DATABASE

CHAR

ACOS

DAYOFMONTH

IFNULL

CONCAT

ASIN

DAYOFWEEK

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


263


Data Store

String Functions

Numeric Functions

Timedate Functions

System Functions

Sybase

ASCII

ABS

DAYNAME

DATABASE

CHAR

ACOS

DAYOFMONTH

IFNULL

CONCAT

ASIN

DAYOFWEEK

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


Outer Escape Sequences

Outer Escape Sequences JDBC s the SQL92 left, right, and full outer syntax. The escape sequence for outer s is: {oj outer-}

where outer- is: table-reference {LEFT | RIGHT | FULL} OUTER {table-reference | outer-} ON search-condition

where: table-reference is

a database table name search-condition is the condition you want to use for the tables For example: SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status FROM {oj Customers LEFT OUTER Orders ON Customers.CustID=Orders.CustID} WHERE Orders.Status='OPEN'

Table 28 lists the outer escape sequences ed by Database Service JDBC drivers for each data store. Table 28. Outer Sequences ed by Database Service JDBC Drivers

Data Store


Progress OpenEdge

Left outer s Right outer s Nested outer s

DB2


Informix



265

Chapter 10: SQL Escape Sequences for JDBC Table 28. Outer Sequences ed by Database Service JDBC Drivers

Data Store


Oracle



Left outer s Right outer s Full outer s Nested outer s

Sybase


Procedure Call Escape Sequences A procedure is an executable object stored in the data store. Generally, it is one or more database queries that have been precompiled. The escape sequence for calling a procedure is: {[?=]call procedure-name[(parameter[,parameter]...)]}

where: specifies the name of a stored procedure parameter specifies a stored procedure parameter procedure-name

Note For DB2, a schema name cannot be used when calling a stored procedure. Also, for DB2

UDB 8.1, literal parameter values are ed for stored procedures. Other ed DB2 versions do not literal parameter values for stored procedures.

266


Chapter 11

Configuring SQL Server Windows Authentication

The Progress Sonic Database Service JDBC SQL Server driver s Windows authenticated connections to Microsoft SQL Server 2000 and Microsoft SQL Server 2000 Enterprise Edition (64-bit) in a domain running Windows Active Directory for Windows clients. See Table 29 for a summary of the configuration that is required to use Windows authentication on Microsoft SQL Server with the Database Service JDBC SQL Server driver. Table 29. Configuring Windows Authentication on Microsoft SQL Server

Component

Collection

Microsoft SQL Server Database Server

Set the authentication mode (see“Setting the Authentication Mode” on page 268). Confirm that a Service Principal Name (SPN) is ed for each Microsoft SQL Server instance (see “ing 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 (see “Setting the Active Directory Encryption Property” on page 269).


267

Chapter 11: Configuring SQL Server Windows Authentication

Setting the Authentication Mode To use Windows authentication, the authentication mode in Microsoft SQL Server on the database server can be set to either Windows Only authentication or Mixed authentication. If SQL Server authentication will be used in addition to Windows authentication, set the authentication mode to use Mixed authentication.

ing Service Principal Names (SPNs) An SPN must be ed for each Microsoft SQL Server instance. An SPN is a unique name that maps the Microsoft SQL Server service for a particular machine and port to an name used to start the service (Service Startup ). An SPN is composed of a service class name of MSSQLSvc, the host name of the machine running Microsoft SQL Server, and the port number on which the Microsoft SQL Server instance is listening. For example: MSSQLSvc/DBServer.test:1433

is an SPN for a Microsoft SQL Server instance running on a machine named DBServer in the test domain and listening on port 1433. Check with your system to confirm that the appropriate SPNs have been ed for each Microsoft SQL Server instance. To list ed SPNs, use the following Windows command: ldifde

If necessary, your system can SPNs using the Setspn tool available with the Windows Resource Kit. For example: setspn -A MSSQLSvc/DBServer.test:1433 sqlsvc

s an SPN that maps the Service Startup 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 is changed, SPNs for Microsoft

SQL Server must be deleted and re-ed.

268


Setting the Active Directory Encryption Property

Setting the Active Directory Encryption Property A Windows domain running Windows Active Directory uses the Kerberos authentication protocol to protect logon credentials that travel across the network. Messages ed between the Kerberos Key Distribution Center (KDC), which runs on every domain controller as part of Active Directory, and Microsoft SQL Server are encrypted. The Active Directory property "Use DES encryption types for this " must be set in the Microsoft SQL Server Service Startup on the domain controller. Setting this property is a one-time task that you must do only when the Active Directory is first created. Check with your system to that this property is set for the Microsoft SQL Server Service Startup on the domain controller.


269

Chapter 11: Configuring SQL Server Windows Authentication

270


Part IV

Configuring and Managing BPEL Services

Part IV explains how to configure and manage BPEL services using the Sonic Management Console, and contains the following chapters: ● “Configuring BPEL Services” ● “Managing BPEL Services”


271

272


Chapter 12

Configuring BPEL Services

This chapter describes how to configure BPEL services using the Sonic Management Console. This chapter contains the following sections: ● “Overview of BPEL Service Initialization Parameters” ● “Specifying a BPEL Archive (.bpar)” ● “Setting Persistence Options” ● “Enabling Audit Trails” ● “Audit Trails and Persistence” ● “Setting a Default Partner Link”


273

Chapter 12: Configuring BPEL Services

Overview of BPEL Service Initialization Parameters A BPEL project contains a single BPEL service and one or more BPEL processes. A BPEL service can execute a single BPEL process or multiple processes. This chapter explains how to configure BPEL services using the Sonic Management Console (SMC). (See the Progress Sonic BPEL Server Developer’s Guide in the Sonic Workbench (Eclipse) help for detailed information about BPEL services and processes.) Note In the development environment, you can also configure BPEL Service parameters using

the BPEL Service editor in Sonic Workbench. See the BPEL Service Editor section of the Sonic Workbench (Eclipse) help for information. The BPEL service configuration pane in the SMC includes areas for viewing and configuring Service Maintenance parameters and Initialization parameters, as shown in this example using the sample BPEL service, LoanApproval:

274


Overview of BPEL Service Initialization Parameters

The Service Maintenance parameters are configured as for any ESB service: ● Service Name ● Entry Endpoint ● Exit Endpoints ● Fault Endpoint ● Rejected Message Endpoint ● WSDL URL The WSDL URL is exposed when BPEL processes are used directly by other services on the ESB. Each BPEL process has a separate WSDL, which is configured in the development environment in Sonic Workbench. For information about configuring these parameters, see the Progress Sonic BPEL Server Developer’s Guide in the Sonic Workbench (Eclipse) help.


275


BPEL services have the following Initialization Parameters: Initialization Parameter

Description

BPEL Archive

The URL of a BPEL archive file (*.bpar) located in the Sonic file system. Required. See “Specifying a BPEL Archive (.bpar)” on page 277

Staging Directory

Enter a local file system directory where the BPAR can be unpacked. The default value is a directory named bpel_staging, relative to the working directory of the ESB container in which the service is deployed (./bpel_staging). Required. Note: The BPEL service may delete files in this directory on service startup.

276

Persistence

Select a value to define how the service is to persist (if at all) its state. The default value is Embedded Storage. Required. See “Setting Persistence Options” on page 278.

Enable Audit Trail Recording

Select whether audit trails are captured for process instances. The default value is True. Required. See “Audit Trails and Persistence” on page 283.

Default Partner Link

Specify the default process and partner link to use. Optional. See “Setting a Default Partner Link” on page 284.

HTTP Callback URL

The address used as the Reply To address when using WSA headers in asynchronous invocations. Optional.


Specifying a BPEL Archive (.bpar)

Specifying a BPEL Archive (.bpar) A BPAR file (*.bpar) is an archive of all resources required to execute a set of BPEL processes. A BPAR is created by Sonic Workbench when a BPEL project is ed. When configuring a BPEL service in the SMC you must point to an existing BPAR file. A single BPAR can be used by one more than one service. (See the Progress Sonic BPEL Server Developer’s Guide in the Sonic Workbench (Eclipse) help for more information about BPAR files.) Note It is recommended that BPAR files be stored in the Sonic file system (sonicfs://),

however, local system paths may be specified. ◆ To specify a BPEL archive file: 1.

In the Init Parameters area of the SMC, click ... next to the BPEL Archive field to open the Edit BPEL Archive file chooser, as shown in this example:

2.

Browse to and select a BPEL archive file (*.bpar).

3.

Click Open. The URL of the BPEL archive file is now displayed in the BPEL Archive field of the SMC.


277


Setting Persistence Options Persistence refers to the storage of active processes deployed to a server. Engine persistence must be configured to allow persistent processes and audit trails (see “Enabling Audit Trails” on page 282). If a service is configured to allow persistence, each process can then be configured to utilize it or not using its deployment descriptor file (*.bpdd). See the BPEL Deployment Descriptor editor section of the Progress Sonic BPEL Server Developer’s Guide in the Sonic Workbench (Eclipse) help for information. BPEL services can run in either of two process modes: ● Persistent process mode: In this mode, BPEL process instances can have their lifetimes persist across container lifetime. All state information is stored in the server database. The persistent processes are ed by either the embedded Hypersonic database, or an external database (either MySQL or Oracle). To select this mode, select the configuration option Embedded Storage (Hypersonic database) or Other Database (MySQL or Oracle) option for the persistence. The default process mode for BPEL services is Embedded Storage (Hypersonic database). When using an external database, each BPEL service instance must be configured with its own database. (Multiple databases can be created on the same server.) When using the embedded database, the service manages a separate instance for each service instance.

Important

●

Transient process mode: In this mode, processes that have not completed when the service container is shut down are terminated at shutdown. No process information is stored in the server database when a process terminates. To select this mode, select the In Memory configuration option for the persistence.

A BPEL service must be configured with persistence to allow persistence for any of the processes deployed in it. Deploying persistent processes into a service configured in transient mode effectively disables persistence for the process. Service and process persistence modes are summarized in the following table:

278

Service

Process

Persistent

Can be Persistent or Transient, as configured for the process.

Transient

Always Transient, regardless of process configuration.


Setting Persistence Options

The following procedure explains how to set the persistence for a BPEL service using the SMC. ◆ To set persistence for a BPEL service: 1.

In the Init Parameters area of the SMC, click ... next to the Persistence field. The Persistence Editor dialog box opens:

Embedded Storage is the default persistence setting. 2.

Select the Data Source Type, either: ■ In Memory — This option sets the persistence mode to transient. When you select this option, the Persistence field in the Init Parameters section of the SMC will display the value In Memory.


279

Chapter 12: Configuring BPEL Services ■

■

Embedded Storage — This option sets the persistence mode to persistent, using

the embedded Hypersonic database. Optionally, you can specify a storage directory for the persistent processes. If you do not specify a storage directory, the default is the staging directory. The database is created as needed in the specified storage directory when the service starts. If you move or delete the database, a new database is created the next time the service starts. Existing databases in the staging directory are deleted (on service restart) when you specify a new storage location. When you select Embedded Storage, the Persistence field in the Init Parameters section of the SMC will display the value Embedded Storage. (This is the default mode.) Other Database — This option sets the persistence mode to persistent, using a database other than the embedded database. When this option is selected, you must provide additional details required to connect to the database. Only Oracle and MySQL database types are ed (see Step 3). When you select this option, the Persistence field in the Init Parameters section of the SMC will display a value for the selected database type: ❑ Oracle: type=”oracle” name=”name” host=”localhost” port=”1521” ❑

MySQL: type=”mysql” name=”dbname” name=”name” host=”localhost” port=”1521”

When using an external database, each BPEL service instance must be configured with its own database.

Important

3.

If you selected Other Database as the data source type, enter the following Database Options: ■ ■ ■ ■ ■ ■

Important

280

Database Type — Select either Oracle or MySQL Database Name — Optional Machine Name — Optional Database Port — Optional name — Optional — Optional

When using an Oracle or MySQL database, you must add the JDBC driver JAR file to the container classpath (see “Adding JAR files to an ESB Container” on page 63 for instructions).


Setting Persistence Options 4.

Click OK to set the persistence mode and close the dialog box.


281


BPEL Development Container Configuration The BPEL development container, dev_BPEL, is configured to terminate all process instances at startup. This container uses embedded storage by default. All historical information (terminated processes and audit trails) remains available in the database and can be accessed through the SMC Management tab. You can safely delete the database from the storage directory.

Enabling Audit Trails An audit trail captures a history of the process instance as it executes. You can query and view this history under the Manage tab in the SMC (see “Viewing Audit Trails” on page 294). Note Audit trails are only ed in persistent process mode by selecting either Embedded Storage or Other Database for the persistence parameter (see “Setting Persistence

Options” on page 278). As with persistence, you can configure audit trails for each process using its deployment descriptor file (*.bpdd) (see the BPEL Deployment Descriptor editor section of the Progress Sonic BPEL Server Developer’s Guide in the Sonic Workbench (Eclipse) help for information). If audit trails are enabled for the service, then the per-process settings for audit trail (if any) are used. If audit trails are disabled for the service, then the perprocess settings are ignored and audit trails are always disabled. See “Viewing Audit Trails” on page 294 for information about the details you can view is audit trails. ◆ To enable audit trail recording: ❖

282

In the Init Parameters area of the SMC, select True from the Enable Audit Trails pulldown list. (Selecting False disables audit trails.)


Audit Trails and Persistence

Audit Trails and Persistence Audit trails are stored in the database with the process instance state (when using persistent process mode). The following modes of operation are typical: ● Persistent process mode with audit trails enabled — This is the standard configuration. All current and historical process state is saved. ● Non-persistent process mode with audit trails not enabled — No process state is saved. Process instances do not survive a container restart and 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.


283


Setting a Default Partner Link When a BPEL Service is invoked it uses WS-Addressing reference parameters to identify the process and partner link associated with the invocation. If the message does not specify this information then the default process and partner link are used. The default partner link is optional. If no default is specified and the service cannot determine the process and partner link from the invocation message, the service will produce a fault. The processes (and partner links) in the Edit Default Partner Link dialog box are obtained from the BPEL archive, so you must specify the archive before you can edit the default partner link. You can set or edit the default partner link for a BPEL service when configuring the service in the SMC. ◆ To set or edit the default partner link: 1.

In the Init Parameters area of the SMC, click ... to the right of the Default Partner Link field. The Default Partner Link dialog box opens, as shown in this example:

If the BPEL service does not have any partner link configured, then the dialog box displays the value None.

284

2.

Select the Process and Partner Link for the BPEL service from the pull-down lists of processes and partner links.

3.

To remove a partner link, click Clear.


Considerations with Dehydrated Processes

Considerations with Dehydrated Processes With dehydration, Sonic BPEL Server stores the process and its state in the database while waiting for a response, thus freeing up server resources. Hydration occurs when the engine receives the response and restores the process and its state from the database and continues executing the process. Process instances cannot be dehydrated unless the following conditions are met: ● You are not in development mode (TEST_CONTAINER_MODE is not set, or set to FALSE). (See “Setting Test Mode for ESB Containers Used in Development” on page 62.) ● You are using a Persistent store (that is, not In Memory). (See “Setting Persistence Options” on page 278.) ● All activities must be in a waiting state (that is, no alerts are set). ● There are no synchronous inbound connections.


285


286


Chapter 13

Managing BPEL Services

This chapter describes how to manage BPEL services. This chapter contains the following sections: ● “Overview of BPEL Service and Process Management” ● “Clearing Process History” ● “Terminating Processes” ● “Searching for Process Instances” ● “Viewing Audit Trails” ● “BPEL Profiling”


287


Overview of BPEL Service and Process Management Under the Manage tab in the Sonic Management Console (SMC), you can view BPEL services in ESB containers and perform management operations. You can also view and manage all BPEL processes for each BPEL service. ◆ To view and manage BPEL services and processes in the SMC: ❖

In the left pane of the SMC under the Manage tab, select a BPEL service and view the associated processes in the right pane. In this example, selecting the sample BPEL service LoanApproval in the left pane displays the processes loanAssessor, pubSubApproval, and loanApproval in the right pane:

Management operations can be performed on all the processes in a BPEL service when executed on the right pane, or on a specific process when executed in the left pane. For example, right-clicking a service in the left pane and selecting Terminate All terminates all instances of all processes for that service. Right-clicking a process in the right pane and selecting Terminate All terminates only instances of the selected process.

288


Clearing Process History

The SMC provides the following management capabilities for BPEL services and processes: ● Clear history for a process or for all processes in a service (see “Clearing Process History” on page 289). ● Terminate a process or all processes in a service (see “Terminating Processes” on page 290). ● Search for a set of process instances that match your specified criteria (see “Searching for Process Instances” on page 290). ● View audit trails for a selected process instance (see “Viewing Audit Trails” on page 294). ● View aggregate information for all the process instances created by a selected process (see “BPEL Profiling” on page 296).

Clearing Process History You can clear the history for a single process (for all its expired instances) or for all processes in a service. Clearing the history removes audit trails and terminated process instances. ◆ To clear process history: 1.

To clear the process history for all processes in a service, right-click on a BPEL service (in the left pane) and select Clear History. The Clear History dialog box opens:

Select whether to remove only processes that ended on or before a cutoff date (you must specify the date), or to remove all processes.


289

Chapter 13: Managing BPEL Services 2.

To clear the process history for a selected process, right-click on a BPEL process (in the right pane) and select Clear History. The Clear History dialog box opens:

Select whether to remove only instances of the selected process that ended on or before a cutoff date (you must specify the date), or to remove all instances of the selected process.

Terminating Processes You can terminate a single process or all processes in a service. ◆ To terminate processes: 1.

To terminate all processes in a service, right-click on a BPEL service (in the left pane) and select Terminate All. This action terminates all live instances of all the processes listed for the BPEL service.

2.

To terminate a selected process, right-click on a BPEL process (in the right pane) and select Terminate All. This action terminates all live instances of the selected process.

Searching for Process Instances You can use Process Instance Search tool to find instances of a process that match a set of criteria. You can specify the following search criteria: ● Process instance state (live, terminated, or either) ● Start or termination time ● Received or sent message parts ● XPath expressions, which include access to process variables Note If you search for all instances of a process, you cannot also select a start or termination

time.

290


Searching for Process Instances

The following procedure explains how to search for BPEL process instances using the Process Instance Search tool in the SMC. ◆ To search for BPEL process instances: 1.

In the Manage tab of the SMC, select a BPEL service in the left pane, then select a BPEL process in the right pane. In the lower right pane, click Search. The Process Instance Search window opens, as shown in this example using the sample BPEL process, pubSubApproval:

2.

In the Search Criteria section specify a Search Filter: ■

All Instances

■

Live Instances Terminated Instances

■

Note

If you select All Instances of a process, you cannot also select a start or termination time.


291

Chapter 13: Managing BPEL Services 3.

4.

Optionally, in the Date section, enter a date and time in either or both the Started After and Terminated Before fields. When the Date is specified, a search returns processes as follows for different Search Filter selections: Search Filter

Processes Returned by Search

All Instances

The Started After and Terminated Before fields are disabled when All Instances is selected.

Live Instances

Returns processes that started between the times specified in the fields Started After and Terminated Before.

Terminated Only

Returns processes that terminated between the times specified in the fields Started After and Terminated Before.

Optionally, in the Messages section, click Add to specify the following search criteria in the table: ■ Destination — Select Any, Inbound, or Outbound (Required) ■ ■ ■ ■

If you specify an asterisk (*) as the value for any of the criteria, that value is ignored.

Note 5.

Note

292

Message Namespace Message Local Name Part Search Value

Optionally, in the Boolean XPath Expressions section, click Add to specify the comparison of a BPEL variable. The following expressions allow access to variables and their properties: Variable

Description

$variableName

The value of the variable.

bpws:getVariableProperty(‘name’,‘property’)

The value of the property with respect to the variable identified.

The properties must be specified as namespace qualified identities. The namespace prefixes available are those defined in the BPEL process (see the Progress Sonic BPEL Server Developer’s Guide in the Sonic Workbench (Eclipse) help for information about defining namespaces in a BPEL process). Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

Searching for Process Instances

Specifying an XPath expression enables you to select process instances based on variable values and conditions applied to them. The conditions are expressed as XPath 2.0 expressions. 6.

Click Search. The search results are displayed in the Process Instance Search Results section, as shown in this example:

The search results are a list of process instances satisfying your search criteria with the following column values: ■ Process ID — The unique ID of the process instance ■ Terminated — The date, if terminated, or live. ■ Correlation (if correlation set(s) are defined for the process) — Zero or more columns. Each correlation set is potentially an array of properties. The column name is the correlation set name and the value is a comma separated list of property values. For example: Property1=value,Property2=value

The correlation column is dynamic, and is only shown when a process has correlation values.

Note

7.

To terminate a process instance, select the instance in the Process Instance Results section and click Terminate.

8.

To view the audit trail of a process instance, select the instance in the Process Instance Results section and click Audit Trail. (See “Viewing Audit Trails” on page 294.)

9.

Close the Process Instance Search window to return to the SMC.


293


Viewing Audit Trails When a BPEL service configuration has the Enable Audit Trails option set to True (see “Audit Trails and Persistence” on page 283) and the Persistence option set to something other than In Memory (see “Setting Persistence Options” on page 278), you can view activities and event details of a BPEL process instance. ◆ To view audit trails and event details: 1.

294

In the Search Process Instance window, select a process instance and click Audit Trail (see “Searching for Process Instances” on page 290). The Audit Trail dialog box opens and displays the audit trail for the selected process instance, as shown in this example using the sample BPEL process, loanApproval:


Viewing Audit Trails

The Audit Events pane displays the following information: ■

Activity Type

■

Activity XML:ID— The value of the ID attribute in the process’s XML document

■

Activity ID — A unique number for the specific instance of the activity. When

■

multiple audit events are logged for the same activity, this number can be used to correlate all related events. (For example, see Activity ID 27 in the preceding example.) Time — The time, including date, at which the activity was recorded.

Many activities generate multiple audit trail events. For instance, many activities generate a START event and a COMPLETE event, as in the preceding example.

Note

2.

Select an activity in the left pane. If the activity has additional details, the details of the selected activity are displayed in the Events Details pane, as shown in this example:

Event details include the following information, depending on the selected activity: ■ Messages received by a RECEIVE activity ■ Messages sent by an INVOKE activity ■ Variable manipulation performed by an ASSIGN activity ■ Fault information Progress Sonic ESB Product Family: Configuration and Management Guide V7.6

295


BPEL Profiling You can view the activities of a BPEL process in the BPEL Profile dialog box under the Manage tab in the SMC. This information represents aggregate performance information of all process instances recorded for a particular process in the service. Clearing the history (see “Clearing Process History” on page 289) resets the profiling information. ◆ To view detailed activities of a BPEL process: ❖

In the Manage tab of the SMC, select a BPEL process then click BPEL Profile. The BPEL Profile dialog box opens, as shown in this example:

The BPEL Profile dialog box lists the activities for a process by ID, and contains the following information: ■

Activity XML:ID

■

Activity Description, including the name attribute specified in the BPEL process,

if any

296

■

Times Completed: Minimum, average, and maximum [ms]

■

Individual time: Minimum, average, and maximum [ms]

■

Total time: Minimum, average, and maximum [ms]


Index

A action flows tuning 133 Activation Daemon 78, 173 retry rules 81 add directory command 35 add file command 35 add license container command 39 address factory 50 address space size 136 addresses 85 alternate servers 172 DB2 186 Informix 202 Microsoft SQL Server 228 Oracle 213 Progress OpenEdge 176, 181 Sybase 243 application performance transformation 148 XML document update 133 applyMap command 44 arguments backup utility 156 restore utility 159

B backing up document collections 152 backup image files 155

backup record files 155 backup utility 156 backups full 152, 157 incremental 152, 158 scheduling 152 Blob and binary stream data (DB2) 196 boot files 51 BPAR 277 BPEL archive file 277 audit trail 282, 294 partner link 284 process instance search 290 profiling 296 BPEL services configuring 273 broker Actional instrumentation 54 payload in Actional instrumentation 54

C cache size 138 cache resources 136 certificate-based authentication 108 cipher suites 108 clearing management container logs 67 client load balancing 168 code page


297

Index

converting character data DB2 188 Informix 202 Microsoft SQL Server 229 Sybase 244 overriding DB2 188 Informix 202 commands, ESB Tool 33 commit transaction if idle 135 concurrency control and performance 130 concurrent durable subscriptions 91, 97 configuring BPEL services 273 connections 103 SonicMQ endpoints 95 connect command 34 connecting to domain manager 20 connection configuring 103 connection URLs 105 deleting 109 ESB 54 for endpoints 96 HTTP(S) 54 JMS 54 maximum at least once sessions 106 maximum best effort sessions 106 maximum exactly once sessions 106 maximum receive sessions 106 maximum Web Service sessions 106 name 105 name of domain 22 ping interval 107 type 105 connection failover 169 alternate servers DB2 186 Informix 202 Microsoft SQL Server 228 Oracle 213 Progress OpenEdge 176, 181 Sybase 243 connection retry 170 ConnectionRetryCount DB2 189 Informix 203 298

Microsoft SQL Server 230 Oracle 215 Progress OpenEdge 177, 181 Sybase 245 ConnectionRetryDelay DB2 190 Informix 204 Microsoft SQL Server 231 Oracle 216 Progress OpenEdge 177, 181 Sybase 246 DatabaseName Progress OpenEdge 178, 181 connection URLs connections 105 domain 22 container list command 39 createMap command 44

D data stores backing up 152 restoring from backup 158 date format (Informix) 205 DB2 code page character data, converting 188 connection properties alternate servers 186 CodePageOverride 188 ConnectionRetryCount 189 ConnectionRetryDelay 190 DiagnosticFilename 191 InsensitiveResultSetBufferSize 192 LoadBalancing 193 MaxPooledStatements 194 ConnectionRetry 189 ConnectionRetryDelay 190 DBClob data type mapping 200 load balancing 193 scalar functions 260 state information log 191 DBDate (Informix) 205 debug tracing 75 debugging 123


Index

delete command 36, 38 delete directory command 36 delete file command 34 deleting SonicMQ connections 109 SonicMQ endpoints 99 stored data, performance 144 destination name for endpoints 97 DiagnosticFilename DB2 191 Informix 206 Microsoft SQL Server 231 Oracle 216 Sybase 246 disconnect command 34 document collections archiving 144 backing up 152 indexes 140 tuning disk storage 143 domain manager connecting to 20 starting 20 domains connection name 22 connection URL(s) of management broker 22 name 22 DRA, using 93 dump command 38 durable subscription, concurrent 97

E enable Actional instrumentation broker 54 endpoints configuring 95 connections 96 deleting 99 durable subscription 97 entry 86 exit 86 fault 86 JMS destination name 97 JMS destination type 96

load balancing 98 message prefetch count 98 message prefetch threshold 98 name 96 priority 97 Qualify of Service 96 RME 87 shared subscriptions 98 time to live 98 WSDL URL 96 entry endpoints 86 envelope factory 50 ESB (JMS) connection 54 ESB 33 ESB 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


299

Index

H

J

HTTP routing connection 54 http_defaultConnection 96

JMS destination type 96 JMS destinations 89 jms_defaultConnection 96

I import archive command 45 import command 38 import file system command 45 incremental backup 152, 158 indexes document collections 140 value 146 Informix code page character data, converting 202 connection properties alternate servers 202 CodePageOverride 202 ConnectionRetryCount 203 ConnectionRetryDelay 204 DBDate 205 DiagnosticFilename 206 InformixServer 206 InsensitiveResultSetBufferSize 206 LoadBalancing 207 MaxPooledStatements 208 ConnectionRetry 203 ConnectionRetryDelay 204 date format 205 load balancing 207 scalar functions 261 state information log 206 InsensitiveResultSetBufferSize DB2 192 Informix 206 Microsoft SQL Server 232 Oracle 217 Progress OpenEdge 178 Sybase 247 instrumentation payload, broker 54 instrumentation, broker 54 invalid archive address notification 121

300

L launching management containers 66 list command 37 listener threads, tuning 135 listeners 58 listeners, number 61 load balancing 168 DB2 193 Informix 207 Microsoft SQL Server 233 Oracle 218 Sybase 248 load balancing, endpoints 98 LoadBalancing Progress OpenEdge 179, 181 log files 155 logging 75, 123

M management broker connection URL(s) 22 management container logs clearing 67 saving 67 viewing 67 management containers launching 66 operations 66 reload command 40 resetting metrics 66 restarting 66 resume command 40 shutdown command 39 shutting down 66 status command 40 suspend command 40 maximum


Index

at least once sessions 106 best effort sessions 106 exactly once sessions 106 receive sessions 106 Web Service sesions 106 MaxPooledStatements DB2 194 Informix 208 Microsoft SQL Server 234 Oracle 219 Progress OpenEdge 179 Sybase 249 message factory 50 prefetch threshold 98 message prefetch count 98 message routing tuning 141 metrics 118 Microsoft SQL Server code page character data, converting 229 connection properties alternate servers 228 CodePageOverride 229 ConnectionRetryCount 230 ConnectionRetryDelay 231 DiagnosticFilename 231 InsensitiveResultSetBufferSize 232 LoadBalancing 233 MaxPooledStatements 234 ConnectionRetry 230 ConnectionRetryDelay 231 load balancing 233 scalar functions 263 state information log 231

N names connections 105 domain 22 endpoints 96 nonindexed XPath traversal 147 notifications 71, 121

O operations management containers 66 Oracle connection properties alternate servers 213 ConnectionRetryCount 215 ConnectionRetryDelay 216 DiagnosticFilename 216 InsensitiveResultSetBufferSize 217 LoadBalancing 218 MaxPooledStatements 219 ConnectionRetry 215 ConnectionRetryDelay 216 load balancing 218 scalar functions 262 state information log 216 outer s 265

P 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


301

Index

tuning storage maintenance 144 value indexes 146 XML document update 133 XML Service 133 XPath processing 146 XPath, nonindexed traversal 147 XSLT node selection 148 XSLT output generation 149 XSLT template matching 149 ping interval, connection property 103, 107 PortNumber Progress OpenEdge 180, 181 primary servers 172 priority endpoints 97 Progress OpenEdge 178, 179, 180, 181 connection properties alternate servers 176, 181 ConnectionRetryCount 177, 181 ConnectionRetryDelay 177, 181 DatabaseName 178, 181 Hostname 178 InsensitiveResultSetBufferSize 178 LoadBalancing 179, 181 MaxPooledStatements 179 179 PortNumber 180, 181 SpyAttributes 180 180 ConnectionRetry 177, 181 ConnectionRetryDelay 181 DatabaseName 178, 181 InsensitiveResultSetBufferSize 178 LoadBalancing 179, 181 MaxPooledStatements 179 179 PortNumber 180, 181 scalar functions 259 SpyAttributes 180 180

Q Quality of Service, endpoints 96 queues creating 97 302

R reconnection 101 rejected message endpoint 87 reload command 40 resetting management container metrics 66 resources 23 restarting management containers 66 restoring document collections from full backup images 160 from incremental backup images 161 resume command 40 return set 147

S saving management container logs 67 scalar functions DB2 260 Informix 261 Microsoft SQL Server 263 Oracle 262 Progress OpenEdge 259 Sybase 264 shared subscriptions 91 endpoints 98 shutdown container 39 shutting down management containers 66 Sonic Management Console 21 SonicFS 23 Spy (DataDirect) 180 SpyAttributes Progress OpenEdge 180 SSL CA certificates location 108 certificate chain file 108 certificate chain form 108 cipher suites 108 private key file 108 private key 108 provider class 108 starting domain manager 20


Index

state information log DB2 191 Informix 206 Microsoft SQL Server 231 Oracle 216 Sybase 246 , technical 15 suspend command 40 Sybase code page character data, converting 244 connection properties alternate servers 243 CodePageOverride 244 ConnectionRetryCount 245 ConnectionRetryDelay 246 DiagnosticFilename 246 InsensitiveResultSetBufferSize 247 LoadBalancing 248 MaxPooledStatements 249 ConnectionRetry 245 ConnectionRetryDelay 246 load balancing 248 scalar functions 264 state information log 246

T technical 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 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


303

Index

304


Progress Sonicesb - Configuration And Management Guide jr71

Overview 3e4r5l

More details w3441

Related Documents 3m3m1z

Progress Sonicesb - Configuration And Management Guide jr71

Configuration Management Process Guide 1w2jk

Bsr 64000 Cmts Configuration And Management Guide w12u

Configuration Management 6a234j

Configuration Guide 422q1d

Flexman Installation And Configuration Guide 7631t

More Documents from "ricardo" 2p1f1s

6l6m1j

Drenaje Pluvial.xls 6e2l2z

Ejemplo De Adjetivos Sustantivados 6b171i

Made In Tokyo 236b

6l6m1j

Isotonia 6tg55