Administrative Programming Guide

V7.5
 Progress SonicMQ Administrative Programming Guide V7.5

Copyright © 2007 Sonic Software Corporation. All rights reserved. Sonic Software Corporation is
a wholly-owned subsidiary of Progress Software Corporation.

The Sonic Software products referred to in this document are also copyrighted, and all rights are
reserved by Sonic Software Corporation and/or its licensors, if any. This manual may not, in whole
or in part, be copied, translated, or reduced to any electronic medium or machine-readable form
without prior consent, in writing, from Sonic Software Corporation.

The information in this manual is subject to change without notice, and Sonic Software Corporation
assumes no responsibility for any errors that may appear in this document. The references in this
manual to specific platforms supported are subject to change.

Dynamic Routing Architecture, Sonic ESB, SonicMQ, Sonic Software (and design), Sonic
Orchestration Server, and SonicSynergy are registered trademarks of Sonic Software Corporation in
the U.S. and other countries. Connect Everything. Achieve Anything., Sonic SOA Suite, Sonic
Business Integration Suite, Sonic Collaboration Server, Sonic Continuous Availability Architecture,
Sonic Database Service, Sonic eXtensible Information Server, Sonic Workbench, and Sonic XML
Server are trademarks of Sonic Software Corporation in the U.S. and other countries. Progress is a
registered trademark of Progress Software Corporation in the U.S. and other countries. IBM is a
registered trademark of IBM Corporation. Java and all Java-based marks are trademarks or
registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other
trademarks or service marks contained herein are the property of their respective owners.

SonicMQ Product Family includes code licensed from RSA Security, Inc. Some portions licensed
from IBM are available at http://oss.software.ibm.com/icu4j/.

SonicMQ Product Family includes code licensed from Mort Bay Consulting Pty. Ltd. The Jetty
Package is Copyright © 1998 Mort Bay Consulting Pty. Ltd. (Australia) and others.

SonicMQ Product Family includes the JMX Technology from Sun Microsystems, Inc. Use and
Distribution is subject to the Sun Community Source License available at
http://sun.com/software/communitysource.

SonicMQ Product Family includes software developed by the ModelObjects Group

(http://www.modelobjects.com). Copyright 2000-2001 ModelObjects Group. All rights reserved.
The name "ModelObjects" must not be used to endorse or promote products derived from this
software without prior written permission. Products derived from this software may not be called
"ModelObjects", nor may "ModelObjects" appear in their name, without prior written permission.
For written permission, please contact djacobs@modelobjects.com.

SonicMQ Product Family includes files that are subject to the Netscape Public License Version 1.1
(the "License"); you may not use this file except in compliance with the License. You may obtain a
copy of the License at http://www.mozilla.org/NPL/. Software distributed under the License is
distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
implied. See the License for the specific language governing rights and limitations under the
License. The Original Code is Mozilla Communicator client code, released March 31, 1998. The
Initial Developer of the Original Code is Netscape Communications Corporation. Portions created
by Netscape are Copyright 1998-1999 Netscape Communications Corporation. All Rights
Reserved.

SonicMQ Product Family includes a version of the Saxon XSLT and XQuery Processor from
Saxonica Limited that has been modified by Progress Software Corporation. The contents of the
Saxon source code and the modified source code file (Configuration.java) are subject to the Mozilla
Public License Version 1.0 (the "License"); you may not use these files except in compliance with
the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/ and a copy of
the license (MPL-1.0.html) can also be found in the installation directory, in the
Docs7.5/third_party_licenses folder, along with a copy of the modified code (Configuration.java);
and a description of the modifications can be found in the Progress SonicMQ v7.5 README file.
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY
OF ANY KIND, either express or implied. See the License for the specific language governing
rights and limitations under the License. The Original Code is The SAXON XSLT and XQuery
Processor from Saxonica Limited. The Initial Developer of the Original Code is Michael Kay
http://www.saxonica.com/products.html). Portions created by Michael Kay are Copyright © 2001-
2005. All rights reserved. Portions created by Progress Software Corporation are Copyright © 2007.
All rights reserved.

SonicMQ Product Family includes software developed by Apache Software Foundation

(http://www.apache.org/). Copyright © 1999-2000 The Apache Software Foundation. All rights
reserved. The names "Ant," "Axis," "Xalan," "FOP," "The Jakarta Project," "Tomcat," "Xerces"
and/or "Apache Software Foundation" must not be used to endorse or promote products derived
from the Product without prior written permission. Any product derived from the Product may not
be called "Apache", nor may "Apache" appear in their name, without prior written permission. For
written permission, please contact apache@apache.org.
SonicMQ Product Family includes software Copyright © 1999 CERN - European Organization for
Nuclear Research. Permission to use, copy, modify, distribute and sell this software and its
documentation for any purpose is hereby granted without fee, provided that the above copyright
notice appear in all copies and that both that copyright notice and this permission notice appear in
supporting documentation. CERN makes no representations about the suitability of this software for
any purpose. It is provided "as is" without expressed or implied warranty.
SonicMQ Product Family includes software developed by the University Corporation for Advanced
Internet Development <http://www.ucaid.edu>Internet2 Project. Copyright © 2002 University
Corporation for Advanced Internet Development, Inc. All rights reserved. Neither the name of
OpenSAML nor the names of its contributors, nor Internet2, nor the University Corporation for
Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote products
derived from this software and products derived from this software may not be called OpenSAML,
Internet2, UCAID, or the University Corporation for Advanced Internet Development, nor may
OpenSAML appear in their name without prior written permission of the University Corporation for
Advanced Internet Development. For written permission, please contact opensaml@opensaml.org.

April 2007
 Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
SonicMQ Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 1: Overview of the SonicMQ Administrative APIs . . . . . . . . . . 15

Chapter 2: Using the Configuration API

for the Sonic Management Environment . . . . . . . . . . . . . . . . . . 17
Overview of the Configuration API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Setting Classpaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Configuring SonicMQ Framework Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configuring SonicMQ Broker Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configuring Fault Tolerant Connections and Backup Brokers . . . . . . . . . . . . . . . . . . . . . . . . . 20
Factory Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Code Examples for the Configuration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Connecting to a Domain and Creating a Broker Configuration . . . . . . . . . . . . . . . . . . . . . . . . 23
Creating a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Adding a Broker Configuration to a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Creating Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Creating Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Adding and Modifying an Acceptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Progress SonicMQ Administrative Programming Guide V7.5 5

Contents

Adding a Broker to a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Configuring Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Configure Certificate Revocation List Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Disabling/Enabling the Nagle Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Using Advanced Property Names in Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Configuration Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Using Inner Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Sonic Configuration API Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Java Configuration Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
JavaScript Configuration Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Chapter 3: Using the Runtime API

for the Sonic Management Environment . . . . . . . . . . . . . . . . . .53
Overview of the Runtime API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Programming Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Manageable Components in the Runtime API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Agent Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Activation Daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Collections Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Directory Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Management Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Management Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Instance Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Metrics Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Management Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Metric Alert Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Notifications Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Notification Listeners and Persistent Notification Subscriptions. . . . . . . . . . . . . . . . . . . . . . . .73
Filtering Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Sonic Runtime API Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
JMX DynamicMBean Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Java Proxy API Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
JavaScript Proxy API Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

6 Progress SonicMQ Administrative Programming Guide V7.5

 Contents

Chapter 4: Using the Directory Service API

for Sonic Management Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Overview of the Directory Service (DS) API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Factory Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Principal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Sonic DS API Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Commands that Control Management Security and Auditing . . . . . . . . . . . . . . . . . . . . . . . . . 98
Commands that Set Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Commands that Set Configure Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Commands that Set Manage Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 5: Using the Advanced Security SPIs

for the Sonic Authentication Domains ................... 101
Overview of the PASS SPIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Login SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Login and PasswordUser SPI Implementation in the SonicMQ Runtime . . . . . . . . . . . . . . . 103
Login SPI and JAAS authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Configuring the Login SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Authentication SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Authentication SPI Implementation in the SonicMQ Runtime. . . . . . . . . . . . . . . . . . . . . . . . 109
Configuring the Authentication SPI for an External Authentication Domain . . . . . . . . . . . . 113
Authentication SPI Operations on Broker Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Authenticate Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Getting Credentials After Authenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Management SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Progress SonicMQ Administrative Programming Guide V7.5 7

Contents

8 Progress SonicMQ Administrative Programming Guide V7.5

 Preface

SonicMQ is a fast, flexible, and scalable messaging broker that simplifies the
development and integration of highly distributed enterprise applications. SonicMQ is a
complete implementation of the Java Message Service specification Version 1.1, an API
for accessing enterprise messaging systems from Java programs.
This book provides information about using the SonicMQ Management Application
Program Interfaces (APIs).

Progress SonicMQ Administrative Programming Guide V7.5 9

Preface

About This Manual

This book consists of these sections:
● Chapter 1, “Overview of the SonicMQ Administrative APIs,” introduces the
administrative APIs available with SonicMQ.
● Chapter 2, “Using the Configuration API for the Sonic Management Environment,”
describes using the SonicMQ Configuration API, which provides operations and
attributes to help you configure the Sonic Management Environment.
● Chapter 3, “Using the Runtime API for the Sonic Management Environment,”
describes using the SonicMQ Runtime API, which provides programmatic access to
the Sonic Management Environment at runtime.
● Chapter 4, “Using the Directory Service API for Sonic Management Security,”
describes using the SonicMQ DS API, which provides programmatic access to Sonic
Management Security at runtime.
● Chapter 5, “Using the Advanced Security SPIs for the Sonic Authentication
Domains,” describes the PASS SPIs you can use to implement pluggable
authentication and security functionality in SonicMQ.

10 Progress SonicMQ Administrative Programming Guide V7.5

 Typographical Conventions

Typographical Conventions
This section describes the text-formatting conventions used in this guide and a description
of notes, warnings, and important messages. This guide uses the following typographical
conventions:
● Bold typeface in this font indicates keyboard key names (such as Tab or Enter) and
the names of windows, menu commands, buttons, and other Sonic user-interface
elements. For example, “From the File menu, choose Open.”
● Bold typeface in this font emphasizes new terms when they are introduced.
● Monospace typeface indicates text that might appear on a computer screen other than
the names of Sonic user-interface elements, including:
■ Code examples and code text that the user must enter
■ System output such as responses and error messages
■ Filenames, pathnames, and software component names, such as method names
● Bold monospace typeface emphasizes text that would otherwise appear in monospace
typeface to emphasize some computer input or output in context.
● Monospace typeface in italics or Bold monospace typeface in italics (depending
on context) indicates variables or placeholders for values you supply or that might
vary from one case to another.
This manual 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 A Note flag indicates information that complements the main text flow. Such information
is especially helpful for understanding the concept or procedure being discussed.

Important An Important flag indicates information that must be acted upon within the given context
to successfully complete the procedure or task.

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

Progress SonicMQ Administrative Programming Guide V7.5 11

Preface

SonicMQ Documentation
SonicMQ provides the following documentation:

Title and Format Description

Getting Started with Progress SonicMQ An overview of the SonicMQ architecture and messaging
(PDF) concepts. Guides the user through some of the SonicMQ
sample applications to demonstrate basic messaging features.

Progress SonicMQ Installation and The guide to maintenance of physical installations of

Upgrade Guide SonicMQ software. Shows various ways to run setups and
(PDF) upgrades as well as the features to install on a system
depending upon its intended use. Describes additional on site
tasks such as defining additional components that use the
resources of an installation, creating activation daemons, and
encrypting local files, plus the use of characters and local
troubleshooting tips.

Progress SonicMQ Deployment Guide Describes how to architect topologies of components in

(PDF) broker clusters, fault tolerance, and Dynamic Routing
Architecture. Shows how to use the protocols and security
options that make your deployment a resilient, efficient,
controlled structure. Covers HTTP Direct, Sonic’s technique
that enables SonicMQ brokers to send and receive pure HTTP
messages.

Progress SonicMQ Application Takes you through the Java sample applications to illustrate
Programming Guide the design patterns they offer to your applications. Details
(PDF) each facet of the client functionality: connections, sessions,
transactions, producers and consumers, destinations,
messaging models, message types and message elements.
Complete information is included on hierarchical
namespaces, recoverable file channels, and distributed
transactions.

SonicMQ API Reference Online JavaDoc compilation of the exposed SonicMQ Java
(HTML) messaging client APIs.

12 Progress SonicMQ Administrative Programming Guide V7.5

 SonicMQ Documentation

Title and Format Description

Progress SonicMQ Configuration and Describes the container and broker configuration toolset in
Management Guide detail plus how to use the JNDI store for administered objects,
(PDF) and the certificate manager. Shows how to manage and
monitor deployed components including their metrics and
notifications.

Progress SonicMQ Administrative Provides information about moving development projects into
Programming Guide test and production environments. Describes recommended
(PDF) build procedures, domain mappings, and reporting features.

Management Application API Reference Online JavaDoc compilation of the exposed SonicMQ
(HTML) management configuration and runtime APIs.

Metrics and Notifications API Reference Online JavaDoc of the exposed SonicMQ management
(HTML) monitoring APIs.

Progress SonicMQ Performance Tuning Illustrates the buffers and caches that control message flow
Guide and capacities to help you understand how combinations of
(PDF) parameters can improve both throughput and service levels.

Sonic Event Monitor User’s Guide Provides a logging framework to track, record, or redirect
(PDF) metrics and notifications that monitor and manage
applications.

Progress SonicMQ Administrative Programming Guide V7.5 13

Preface

Worldwide Technical Support

Progress Software’s support staff can provide assistance from the resources on their Web
site at www.sonicsoftware.com. There you can access technical support for licensed
Progress Sonic editions to help you resolve technical problems that you encounter when
installing or using SonicMQ.
When contacting Technical Support, please provide the following information:
● The release version number and serial number of Progress SonicMQ that you are
using. This information is:
■ Listed on your license addendum.
■ Displayed for a broker in its configuration properties’ Product Information
window.
■ Listed at the top of a SonicMQ Broker console window, similar to the following:
SonicMQ Continuous Availability Edition [Serial Number nnn]
Release nnn Build Number nnn Protocol nnn
● The platform on which you are running SonicMQ, as well as any other environment
information you think might be relevant
● The Java Virtual Machine (JVM) that the installation is using
● Your name and, if applicable, your company name
● E-mail address, telephone, and fax numbers for contacting you

14 Progress SonicMQ Administrative Programming Guide V7.5

Chapter 1 Overview of the SonicMQ
Administrative APIs

This book contains information about using the SonicMQ Management Application
Programming Interface (API). This API provides configuration and runtime access to the
Sonic Management Environment, and includes Service Provider Interfaces (SPIs) for
implementing the Pluggable Authentication and Security Service (PASS). The interfaces,
operations, and attributes in this API are documented in the JavaDoc included with your
SonicMQ installation (see sonic_install_root/Docs7.5/api/mgmt_api/index.html).
This book provides an overview of the interfaces located in each of the following
packages:
● Configuration Packages — Use the Configuration API to configure all aspects of
SonicMQ and the Management Framework, including collections, containers,
brokers, clusters, queues, and routings. Get and set individual attributes on a
configuration, create and delete configurations, and manipulate tables and lists.
See Chapter 2, “Using the Configuration API for the Sonic Management
Environment.”
● Runtime Packages — Use the Runtime API to monitor and manage running
containers and components in your management applications. Gather runtime
information and perform operations on manageable entities (containers, components)
in the Sonic environment.
See Chapter 3, “Using the Runtime API for the Sonic Management Environment.”
● Managemement Security — Use the Directory Service API—together with the
Configuration API and the Runtime API—to enable and configure runtime checking
of management permissions, and auditing of configuration and runtime events.
See Chapter 4, “Using the Directory Service API for Sonic Management Security.”

Progress SonicMQ Administrative Programming Guide V7.5 15

Chapter 1: Overview of the SonicMQ Administrative APIs

● Advanced Security Packages — Use the Security SPIs to implement pluggable

authentication and security functionality in SonicMQ. The client, broker, and
framework SPIs provide programming interfaces you can use to authenticate JMS
client applications with external security domains.
See Chapter 5, “Using the Advanced Security SPIs for the Sonic Authentication
Domains.”
The SonicMQ Management API provides configuration and runtime programmatic
access to attributes, operations, metrics, and notifications for the manageable components
of SonicMQ, including the following:

SonicMQ Management API Manageable Components

Runtime API ● Activation Daemon
● Agent (Container)
● Agent Manager
● Broker
● Collections Monitor
● Directory Service
Configuration API ● Activation Daemon
● Authentication Domain
● Broker
● Backup Broker
● Collection
● Collections Monitor
● Container
● Directory Service
Advanced Security SPIs ● Authentication Domain
● Broker

See the Progress SonicMQ Configuration and Management Guide for information about
using the Sonic Management Console (SMC) to access these components.
See the Progress SonicMQ Deployment Guide for detailed information about configuring
and running these components for your own application deployments.

16 Progress SonicMQ Administrative Programming Guide V7.5

Chapter 2 Using the Configuration API for the Sonic
Management Environment

Chapter 2 describes using the SonicMQ Configuration application programming interface

(API), which provides operations and attributes to help you configure the Sonic
Management Environment. This chapter contains the following sections:
● “Overview of the Configuration API” — Introduces this programming interface that
allows you to configure collections, containers, brokers, clusters, queues, and
routings
● “Factory Operations” — Explains how to connect the Configuration API to a running
domain and Directory Service using the MFMgmtBeanFactory or the MQMgmtBeanFactory
● “Code Examples for the Configuration API” — Provides code examples that
demonstrate how to program using the Configuration API for some of the common
tasks performed using this API
● “Configuration Names” — Describes how to name and organize your components
● “Using Inner Classes” — Describes inner classes, used by the Configuration API to
structure parameters, lists, and tables
● “Sonic Configuration API Samples” — Explains how to access sample applications
to help you get started with the Configuration API

Progress SonicMQ Administrative Programming Guide V7.5 17

Chapter 2: Using the Configuration API for the Sonic Management Environment

Overview of the Configuration API

The Configuration API provides a programming interface that allows you to configure all
aspects of SonicMQ, including collections, containers, brokers, clusters, queues, and
routings. The Configuration API provides methods to perform such operations as getting
and setting individual attributes on a configuration, creating and deleting configurations,
and manipulating tables and lists.
The Configuration API is located in the following packages:
● com.sonicsw.ma.mgmtapi.config.*
● com.sonicsw.mf.mgmtapi.config.*
● com.sonicsw.mq.mgmtapi.config.*

See the Configuration API online documentation for detailed information about the
interfaces, classes, and methods contained in these interfaces. The API documentation is
available online at: sonic_install_root/Docs7.5/api/mgmt_api/index.html.

Setting Classpaths
Several interfaces provide a setClasspath(String) method:
● ActivationDaemonBean
● AgentManagerBean
● BackupBrokerBean
● BrokerBean
● CollectionsMonitorBean
● ContainerBean
● DirectoryServiceBean
While you can provide a delimited list for compound classpath entries, the delimiter in the
method is always semicolon (;) regardless of the target platform. For example:
setClasspath(“/usr/sonic;/opt/bin;foo/bar”)
When the defined configuration is deployed, the platform specific delimiter—colon under
UNIX and Linux, semicolon under Windows—will be appropriately generated in the
classpath.

18 Progress SonicMQ Administrative Programming Guide V7.5

 Overview of the Configuration API

Configuring SonicMQ Framework Components

The package com.sonicsw.mf.mgmtapi.config.* contains interfaces that allow you to
configure framework components that include the following:
● Agent Manager
● Activation Daemons
● Authentication Domains
❍ Users
❍ Groups
● Collections
● Collections Monitor
● Containers
● Directory Service

Configuring SonicMQ Broker Components

The SonicMQ broker package com.sonicsw.mq.mgmtapi.config.* contains interfaces that
allow you to configure components that include the following:
● Acceptors
● Authorizations Policies
❍ ACLs
❍ QoP
● Brokers
● Backup Brokers
● Clusters
● Global Subscriptions
● Queues
● Replication Connections for Fault Tolerance
● Routings

Progress SonicMQ Administrative Programming Guide V7.5 19

Chapter 2: Using the Configuration API for the Sonic Management Environment

Configuring Fault Tolerant Connections and Backup Brokers

The Configuration API provides attributes and operations to configure fault tolerant
management components and configure backup brokers for your applications. These
attributes and operations are accessible through interfaces in the packages
com.sonicsw.mf.mgmtapi.config.* and com.sonicsw.mq.mgmtapi.config.*.

The com.sonicsw.mf.mgmtapi.config.* interface allows you to configure fault tolerance

parameters of the Directory Service and Agent Manager components.
The SonicMQ broker com.sonicsw.mq.mgmtapi.config.* interface allows you to
configure a broker components to support a backup broker and replication connections.
See the Progress SonicMQ Deployment Guide for information about fault tolerant
management and using fault tolerant connections and backup brokers in your
applications.

Factory Operations
To connect the Configuration API to a running domain and Directory Service use one of
the following two factories:
● MFMgmtBeanFactory — Use this factory if you intend to configure only framework
components
● MQMgmtBeanFactory — Use this factory if you want to configure brokers and
clusters in addition to framework components
The MQMgmtBeanFactory factory extends MFMgmtBeanFactory and contains all the beans
related to the Sonic broker and framework.
Use factory operations to:
● Connect to and disconnect from a domain
● Get the names of all available configurations of a particular type
● Get an individual configuration
● Create, save, commit, and delete a configuration
● Rollback changes to a configuration (before committing the changes)
● Flush configurations cached in memory

20 Progress SonicMQ Administrative Programming Guide V7.5

 Factory Operations

Important Any configuration created or edited using the Configuration API is not stored to the
Directory Service until you explicitly save it and then commit to save to the Directory
Service.
When committing transactions, it is more efficient to use smaller transactional units. For
example, instead of committing a single transaction containing 1000 containers or 200
brokers, commit several smaller transactions containing fewer containers or brokers. In
general, your transactions should not include more than:
● 1000 users
● 500 containers
● 100 brokers

Use the saveBrokerBean( ), commit( ), rollback( ), and flush( ) operations as follows:

● saveBrokerBean( ) — Use saveBrokerBean( ) operations work while creating
various parts of a configuration (base broker bean, routes) for non-secure brokers.
When creating secure brokers, saveBrokerBean( ) operations fail when duplicate item
names are found.
● commit( ) — After you edit and save changes to a configuration, use the commit( )
operation to send the configuration to the Directory Service. You must use commit( )
before generating a boot file.
When your configuration is a broker with security enabled, you must use commit()
after the first call to saveBrokerBean() for a given IBrokerBean object. Multiple
saveBrokerBean() calls can be made subsequent to that commit, with a final commit()
call after the last saveBrokerBean() call. If you do not execute a commit() after the first
call to saveBrokerBean(), subsequent calls to saveBrokerBean() fail to save it.
● rollback( ) — Use the rollback( ) operation to remove any changes made to
configurations in memory and revert to the conditions that existed when you
connected. Configurations are restored to match those in the Directory Service. You
can rollback( ) before or after using saveBrokerBean( ). After you use commit( ) to
send a configuration to the Directory Service, you cannot rollback( ) to a previous
configuration.
● flush( ) — Use the flush( ) operation to dump configurations cached in memory
after you edit, save, and commit changes to the configurations. Using the flush( )
operation allows you to control the in-memory cache growth, and provides more
efficient performance. To control the memory growth, commit( ) smaller amounts,
then call flush( ) after each commit to clear the in-memory cache. The flush( )
operation removes references to anything you previously loaded, including beans.
You must get the beans again after flushing if you need to reference them in your
code.
Progress SonicMQ Administrative Programming Guide V7.5 21
Chapter 2: Using the Configuration API for the Sonic Management Environment

A newly created configuration has default attribute values where specified in the schema,
and might be missing some required attribute values. If some required values are missing,
you will receive an error message when you try to save the configuration, indicating that
the required values are missing. You can then provide these values and save the
configuration. The Configuration API online documentation details which attribute
values are required, and which are optional. Some attribute values are overwritable, and
can be customized for your configuration. See the Configuration API online
documentation at: sonic_install_root/Docs7.5/api/mgmt_api/index.html.

Code Examples for the Configuration API

The following code examples demonstrate how to program using the Configuration API
for some of the common tasks performed using this API. You can extend these basic
examples for your applications. This section contains code examples for the following
tasks:
● “Connecting to a Domain and Creating a Broker Configuration” on page 23
● “Creating a Container” on page 27
● “Adding a Broker Configuration to a Container” on page 28
● “Creating Queues” on page 28
● “Creating Routes” on page 29
● “Adding and Modifying an Acceptor” on page 32
● “Adding a Broker to a Cluster” on page 35
● “Configuring Security” on page 36
● “Configure Certificate Revocation List Caches” on page 39
● “Disabling/Enabling the Nagle Algorithm” on page 41
● “Using Advanced Property Names in Applications” on page 42

22 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

Note Exception Tracing — A static method in the com.sonicsw.mx.config.util.ConfigHelper

class, printExceptionInfo(Throwable e), recursively processes thrown exceptions to
expose the cause of the exception.
For example:
try
{
MFMgmtBeanFactory factory = new MFMgmtBeanFactory();
factory.connect("Domain1", "tcp://localhost:2506", "", "");
}
catch(Exception e) { ConfigHelper.printExceptionInfo(e) ;}
When, for this example, the jmxri.jar is not accessible, the display shows:
com.sonicsw.ma.mgmtapi.config.MgmtException: Failed to connect to domain :
javax/management/JMRuntimeException
at com.sonicsw.ma.mgmtapi.config.impl.AbstractMgmtBeanFactory.connect
(AbstractMgmtBeanFactory.java:69)
at com.sonicsw.mf.mgmtapi.config.test.MFDomainTest.main
(MFDomainTest.java:18)
Caused by...
java.lang.NoClassDefFoundError: javax/management/JMRuntimeException
...
Hit uncaught exception java.lang.ClassNotFoundException
You can then find that the missing class is in jmxri.jar to resolve the problem.

Connecting to a Domain and Creating a Broker Configuration

These steps show you how to:
● Connect to a domain
● Create a broker configuration
● Save and commit a configuration
● Rollback changes to a configuration
● Flush cached configurations

◆ To connect to a domain:
1. Create a factory.
For example:

MQMgmtBeanFactory domain = new MQMgmtBeanFactory();

Progress SonicMQ Administrative Programming Guide V7.5 23

Chapter 2: Using the Configuration API for the Sonic Management Environment

2. Connect to the domain, supplying:

❍ Directory Service Domain
❍ URL of the Directory Service location
❍ Username
❍ Password
When connecting to a domain set up for fault tolerant management, you can also
call the following methods from the ConfigServer utility to set connection parameters
prior to connecting:

public long getConnectTimeout() { return m_connectTimeout; }

public void setConnectTimeout(long timeout) { m_connectTimeout = timeout; }

public long getRequestTimeout() { return m_requestTimeout; }

public void setRequestTimeout(long timeout) { m_requestTimeout = timeout; }

public boolean isLoadBalancing() { return m_loadBalancing; }

public void setLoadBalancing(boolean val) { m_loadBalancing = val; }

public boolean isUseDRA() { return m_useDRA; }

public void setUseDRA(boolean val) { m_useDRA = val; }

public String getManagementNode() { return m_managementNode; }

public void setManagementNode(String val) { m_managementNode = val;}

For example:

MQMgmtBeanFactory factory = new MQMgmtBeanFactory();

ConfigServerUtility util = factory.getConfigServerUtility();

util.setRequestTimeout(45);

factory.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password

3. Use the domain to retrieve an existing configuration.

For example, to obtain a broker configuration:

IBrokerBean broker = domain.getBrokerBean(“/MyBrokers/Broker1”);

24 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

◆ To create a configuration:
❖ Use one of the create operations.
For example, to create a broker configuration:

IBrokerBean createBrokerBean(“/MyBrokers/Broker1”);

You can use customized code to handle broker-specific operations such as:
■ Setting the broker name
■ Creating a default acceptor and sample queues

◆ To save and commit a broker configuration:

❖ Use one of the save operations then commit.
For example, to save a broker configuration then commit the configuration:
...
domain.saveBrokerBean(IBrokerBean bean);
domain.commit( );

This operation also saves referenced and related beans.

◆ To rollback changes to broker configurations:

❖ Use the rollback operation.
For example, to rollback changes to a configuration you have changed (but not yet
committed):
...
domain.rollback( );

This operation reverts the configuration to match what is in the Directory Service.

Progress SonicMQ Administrative Programming Guide V7.5 25

Chapter 2: Using the Configuration API for the Sonic Management Environment

◆ To flush cached broker configurations:

❖ Use the flush operation.
For example, to flush a configuration cached in memory:
...
domain.flush( );

This operation dumps configurations cached in memory, along with all references to
any beans previously used.
The following example shows how to create a factory to connect to the Directory Service,
load a broker configuration, save and commit changes to the configuration, and flush the
configuration cached memory.

//Create a factory

MQMgmtBeanFactory domain = new MQMgmtBeanFactory();

//Connect to the Directory Service

domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password

// Load the Broker Bean for /Brokers/Broker1

IBrokerBean broker = domain.getBrokerBean(“/Brokers/Broker1”);

. . .
domain.saveBrokerBean(broker);
domain.commit();
domain.flush();

26 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

Creating a Container
The following code, excerpted from the sample CreateContainer.java, shows how to
create a container and set attribute values for the new container:

public class CreateContainer

{
private static final String CONTAINER_NAME = "NewContainer";
public static void main(String[] args)
{
try
{
MFMgmtBeanFactory domain = new MFMgmtBeanFactory();

domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password
...
{
IContainerBean container = domain.createContainerBean("/Containers/"
+ CONTAINER_NAME);
container.setContainerName(CONTAINER_NAME);

//Change some of the container’s attributes values

container.setCommandLine(true);
container.getCache().setCacheDirectory("c:\\Temp");
container.setLogToFile(false);

IContainerBean.IConnectionType connection = container.getConnection();

connection.setConnectionURLs("tcp://localhost:22000");
connection.setDefaultUser("Administrator");

IContainerBean.IMonitoringType monitor = container.getMonitoring();

monitor.setStatusPollTimeout(60);
monitor.setStatusPollInterval(120);
domain.saveContainerBean(container);
domain.commit();
}
...

See “Create Container Java Sample” on page 47 and “Create Container JavaScript
Sample” on page 51 for information about samples that demonstrate creating a container
using the Configuration API.

Progress SonicMQ Administrative Programming Guide V7.5 27

Chapter 2: Using the Configuration API for the Sonic Management Environment

Adding a Broker Configuration to a Container

The following code shows how to add a broker configuration to a container. Using the
container created in the previous example, this example creates an entry for the broker,
configures the entry, and specifies that the broker will be started when the container starts.
The broker is then added to the container. You can also add other startup parameters to
your code to customize your broker in the container. For example:

...
String brokerComponentName = “myBroker1”;
IBrokerBean bbean = factory.getBrokerBean(“/Brokers/Broker1”);
IContainerBean.IComponentsType containerComponents = container.getComponents();
IContainerBean.IStartupParams startupParams = containerComponents.createEntry();
startupParams.setConfigRef( bBean );
startupParams.setAutoStart( true );
containerComponents.addEntry( brokerComponentName, startupParms );
...

Creating Queues
The following code, excerpted from the sample CreateQueues.java, shows how to create
a queue, add the queue to the list of queues for the broker, and modify some of the queue’s
parameters:

public final class CreateQueues

{
private static final String BROKER_VIEW_NAME = "/Brokers/Broker1";private
static final String QUEUE_NAME = "NewQueue1";

public static void main(String[] args)

{
try
{
MQMgmtBeanFactory domain = new MQMgmtBeanFactory();

domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password
// Load the Broker Bean for /Brokers/Broker1
IBrokerBean broker = domain.getBrokerBean(BROKER_VIEW_NAME);

IQueuesBean.IQueuesSetType queues = broker.getQueuesBean().getQueues();

IQueuesBean.IQueueAttributes queue;

queue = queues.createQueue();
queue.setQueueName(QUEUE_NAME);
// Add the new queue into the list of queues
queues.addQueue(QUEUE_NAME, queue);
domain.commit();

28 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

...
//Get the queue
queue = domain.getBrokerBean("/Brokers/Broker1").getQueuesBean()
.getQueues().getQueue(QUEUE_NAME);
// Change some of the queue values
queue.setQueueMaxSize(12345);
queue.setReadExclusive(true);

domain.commit();
...

See “Create Queues Java Sample” on page 46 and “Create Queue JavaScript Sample” on
page 50 for information about samples that demonstrate creating queues using the
Configuration API. The samples also demonstrate how to check to see if a queue by the
same name already exists for the broker.

Creating Routes
The following code, excerpted from the sample CreateRoutes.java, shows how to get a
list of defined routes for a broker, check to see whether a route already exists, add a route
to the broker, and modify some of the route’s parameters:

public final class CreateRoutes

{
private static final String NOT_DEFINED = "Not defined";
private static final String BROKER_VIEW_NAME = "/Brokers/Broker1";

public static void main(String[] args)

{
try
{
MQMgmtBeanFactory domain = new MQMgmtBeanFactory();

domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password
// Load the Broker Bean for /Brokers/Broker1
IBrokerBean broker = domain.getBrokerBean(BROKER_VIEW_NAME);

// Get the bean containing all route information from this broker
IRoutesBean routes = broker.getRoutesBean();

// Get the set of currently defined routes

IRoutesBean.IRoutingMapType map = routes.getRoutes();
List names = map.getKeyNames();
}

Progress SonicMQ Administrative Programming Guide V7.5 29

Chapter 2: Using the Configuration API for the Sonic Management Environment

// Print information about all currently defined routes.

for(Iterator i = names.iterator(); i.hasNext();)
{
// Each individual route is a separate bean
IMgmtBeanBase item = map.getItem((String)i.next());

// Print out information for this route

printRouteInfo(item);
}
// Now check to see if a HTTP SOAP route called Test1 already exists.
// If it doesn't exist then create it.
// Otherwise we want to set some of the route parameters.

// Routes are stored in a list so we need to iterate through

// them to find our route.
IRouteDirectSoapBean found = null;

System.out.println("Check for Direct Soap Route called Test1");

for(Iterator i = names.iterator(); i.hasNext();)

{
IMgmtBeanBase item = map.getItem((String)i.next());

if(item instanceof IRouteDirectSoapBean)

{
String name =
item.getStringAttribute(IRouteDirectSoapConstants.NODE_NAME_ATTR);
if(name.equals("Test1"))
{
System.out.println(" Test1 already exists");
found = (IRouteDirectSoapBean)item;
break;
}
}
else
throw new MgmtException("Route exists but is the wrong type");
}
if(found == null)
{
System.out.println(" Test1 doesn't exist - create it");
found = routes.createRouteDirectSoapBean();
found.setNodeName("Test1");
map.addItem("Test1", found);
}
// regardless of whether the route already existed or we have
// just created it. Set some of the parameters
found = routes.createRouteDirectSoapBean();
found.setNodeName("Test1");
map.addItem("Test1", found);

30 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

// Set some route parameters

found.setUrl("http://www.someurl.com");
found.setContentReply(true);
found.setContentReplyRetryCount(1);
found.setContentReplyTimeout(100);

IRouteDirectSoapBean.IRoutingDirectContentMapType contentMap =
newRoute.getDirectContentMap();

IRouteDirectSoapBean.IRoutingDirectContentMapItemType mapItem =
contentMap.createItem();
mapItem.setJmsType("XML");
mapItem.setHttpType("text/specialXML");
contentMap.addItem("item1", mapItem);

//Propagate all changes to the DS

domain.saveBrokerBean(broker);
domain.commit();
...

See “Create Routes Java Sample” on page 47 and “Create Routes JavaScript Sample” on
page 50 for information about samples that demonstrate creating routes using the
Configuration API. The samples also demonstrate how to check to see if a route by the
same name already exists for the broker.

Progress SonicMQ Administrative Programming Guide V7.5 31

Chapter 2: Using the Configuration API for the Sonic Management Environment

Adding and Modifying an Acceptor

An acceptor describes a protocol, host name, and port with which a client can connect to
a broker. You can configure a broker with one or more acceptors, designating which type
of connection each acceptor can receive. You can configure either default broker-wide
properties for all of a broker’s acceptors and properties, or individual acceptors that
override the default values. A SonicMQ broker can have acceptors configured for SSL,
TCP, HTTP(S), and HTTP(S) Direct. See the chapter “Configuring Acceptors” in the
Progress SonicMQ Configuration and Management Guide for more information about
acceptors and their properties.
The following code example shows how to create HTTP Direct acceptors for a broker.
This example creates an HTTP Direct acceptor and sets a URL for the acceptor. The
example then creates protocol handlers for that acceptor, setting the HTTP type and JMS
type and creating URLs for the protocol handlers. Finally, this example adds the HTTP
Direct acceptor to the set of acceptors for the broker and saves and commits the changes,
as shown:

package com.sonicsw.mq.mgmtapi.config.test;

import java.util.Iterator;
import java.util.List;

import com.sonicsw.ma.mgmtapi.config.IMgmtBeanBase;
import com.sonicsw.mq.mgmtapi.config.IAcceptorDirectBean;
import com.sonicsw.mq.mgmtapi.config.IAcceptorProtocolBean;
import com.sonicsw.mq.mgmtapi.config.IAcceptorTcpsBean;
import com.sonicsw.mq.mgmtapi.config.IAcceptorUrlReceiveBean;
import com.sonicsw.mq.mgmtapi.config.IAcceptorsBean;
import com.sonicsw.mq.mgmtapi.config.IBrokerBean;
import com.sonicsw.mq.mgmtapi.config.MQMgmtBeanFactory;
public class CreateAcceptors
{
public CreateAcceptors()
{
}
public static void main(String[] args)
{
try
{
MQMgmtBeanFactory domain = new MQMgmtBeanFactory();
domain.connect("Domain1",
"localhost:2506",
"Administrator",
"Administrator");

IBrokerBean bbean = domain.getBrokerBean("/Brokers/Broker1");

32 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

//Get the bean containing all acceptors info for this broker
IAcceptorsBean acceptorsBean = bbean.getAcceptorsBean();
//Get set of currently defined acceptors
IAcceptorsBean.IAcceptorMapType acceptors = acceptorsBean.getAcceptors();
//Create acceptor direct bean (MQ_ACCEPTOR_DIRECT)
IAcceptorDirectBean directBean = acceptorsBean.createAcceptorDirectBean();
directBean.setAcceptorName("DIRECT_ACCEPTOR");
directBean.setAcceptorUrl("http://localhost:8082");
IAcceptorDirectBean.ISslParametersType directParams =
directBean.getSslParameters();
//change enum attribute value
directParams.setSslCertificateChainForm("PKCS12");
//Get set of currently defined protocol acceptors for HTTP direct acceptors
IAcceptorDirectBean.IAcceptorProtocolMapType directType =
directBean.getProtocols();
//create Direct Protocol bean and add it to a set
IAcceptorProtocolBean directProtocolSubbean = directBean.createProtocolBean();
directProtocolSubbean.setDirectName("DIRECT_PROTOCOL");
//--- create content map entry
IAcceptorProtocolBean.IAcceptorDirectContentMapType directContentMap =
directProtocolSubbean.getDirectContentMap();
IAcceptorProtocolBean.IAcceptorDirectContentMapItemType item =
directContentMap.createItem();
item.setHttpType("text");
item.setJmsType("XML"); //possible values: XML, MULTIPART, TEXT, BYTES
directContentMap.addItem("first", item);
directType.addItem("DIRECT_PROTOCOL", directProtocolSubbean);
//--- create URLs
IAcceptorProtocolBean.IHttpDirectURLMapType urls =
directProtocolSubbean.getDirectUrlMap();
IAcceptorUrlReceiveBean urlReceiveBean =
directProtocolSubbean.createAcceptorUrlReceiveBean();
urlReceiveBean.setUser("myUser");
urlReceiveBean.setDestinationName("DESTINATION_NAME");
urlReceiveBean.setUrl("http://localhost:8082");
urls.addItem("DESTINATION_NAME", urlReceiveBean);

//Add direct acceptor to the acceptors set

acceptors.addItem("DIRECT_ACCEPTOR", directBean);

//save modified broker bean

domain.saveBrokerBean(bbean);

//commit changes to DS
domain.commit();

Progress SonicMQ Administrative Programming Guide V7.5 33

Chapter 2: Using the Configuration API for the Sonic Management Environment

The following code example continues from the previous example, and shows how to
modify an acceptor:

//Modify the saved direct bean:

bbean = domain.getBrokerBean("/Brokers/Broker1");
acceptors = bbean.getAcceptorsBean().getAcceptors();;

List names = acceptors.getKeyNames();

for(Iterator iter = names.iterator(); iter.hasNext(); )
{
String name = (String) iter.next();

if (acceptors.getItem(name)instanceof IAcceptorDirectBean)
{
directBean = (IAcceptorDirectBean) acceptors.getItem(name);
//modify acceptor's url
directBean.setAcceptorUrl("http:localhost:8089");
}
}
domain.commit();
domain.disconnect();
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
System.exit(0);
}
}

See the chapter “Configuring Acceptors” in the Progress SonicMQ Configuration and
Management Guide for information about other types of acceptors that can be configured
for a broker.

34 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

Adding a Broker to a Cluster

The following code example shows how to add a broker configuration to a cluster. This
example first creates a cluster bean, gets the broker to add to the cluster, then adds the
broker to the cluster. This example throws an exception if you try to add a security-
enabled broker to a non-secure cluster, as shown:

package com.sonicsw.mq.mgmtapi.config.test;

import com.sonicsw.ma.mgmtapi.config.MgmtException;
import com.sonicsw.mq.mgmtapi.config.IBrokerBean;
import com.sonicsw.mq.mgmtapi.config.IClusterBean;
import com.sonicsw.mq.mgmtapi.config.MQMgmtBeanFactory;
import java.util.*;
public class AddBrokerToCluster
{
private static String CLUSTER_VIEW_NAME = "/Cluster1";

public AddBrokerToCluster()
{
}
public static void main(String[] args)
{
try
{
MQMgmtBeanFactory domain = new MQMgmtBeanFactory();
domain.connect("Domain1",
"localhost",
"Administrator",
"Administrator");
//Create cluster bean
IClusterBean cbean = domain.createClusterBean(CLUSTER_VIEW_NAME);
//get members of a cluster
IClusterBean.IClusterMembers members =
domain.getClusterBean("/Cluster1").getClusterMembers();
//Add broker to the cluster
//Assumes that non-secure broker "Broker2" exists in DS
IBrokerBean bbean = domain.getBrokerBean("/Brokers/Broker2");
members.addItem("Broker2", bbean);
//Note: Throw exception if we try to add security-enabled broker to non_secure
//cluster (Cluster1 in our case)
domain.saveClusterBean(cbean);
domain.commit();
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
System.exit(0);
}
}

Progress SonicMQ Administrative Programming Guide V7.5 35

Chapter 2: Using the Configuration API for the Sonic Management Environment

Configuring Security
The following code, excerpted from the sample CreateRoutes.java, shows how to create
a user in the default authentication domain, create a group in the default authentication
domain, create an access control list (ACL) in the default authorization policy, and create
a quality of protection (QoP) setting in the default authorization policy.
First, connect to the domain and create a user, group, ACL, and QoP in the Authentication
Domain, then commit the changes to the Directory Service, as shown:

public final class SecuritySample

{
private static String DEFAULT_AUTHENTICATION_DOMAIN =
"/Security/Default Authentication";
private static String DEFAULT_AUTHORIZATION_POLICY =
"/Security/Default Policies";

public static void main(String[] args)

{
try
{
MQMgmtBeanFactory domain = new MQMgmtBeanFactory();

domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password
//create a new user in Authentication Domain
createUser(domain);
//create a new group in Authentication Domain
createGroup(domain);
//create a new ACL in Authorization Policies
createACL(domain);
//create a new Qop in Authorization Policies
createQop(domain);
//propagate all changes to the DS
domain.commit();

36 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

Create a new user in the authentication domain, having a user name and password:

private static void createUser(MQMgmtBeanFactory factory) throws MgmtException

{
// Load the Authentication Domain bean
IAuthenticationDomainBean authDomainBean =
factory.getAuthenticationDomainBean(DEFAULT_AUTHENTICATION_DOMAIN);
try
{
//First check if user exists
IAuthenticationUserBean newUser = authDomainBean.getUserBean("Joe");
System.out.println("User <Joe> already exists");
}
catch (MgmtException e)
{
// Create a new user in Default Authentication Domain
// By default it will be added to the PUBLIC group
IAuthenticationUserBean newUser = authDomainBean.createUserBean();
newUser.setUserName("Joe");
newUser.setPassword("Smith");
factory.saveBean(newUser);
}
}

Create a group in the authentication domain. Check whether the group already exists.
Set a group name, create a group member, and add the member to the group, as shown:

private static void createGroup(MQMgmtBeanFactory factory) throws MgmtException

{
// Load the Authentication Domain bean
IAuthenticationDomainBean authDomainBean =
factory.getAuthenticationDomainBean(DEFAULT_AUTHENTICATION_DOMAIN);
try
{
//First check if group exists
IAuthenticationGroupBean marketingGroup =
authDomainBean.getGroupBean("Marketing");
System.out.println("Group <Marketing> already exists.");
}
catch (MgmtException e)
{
//Create a new group and add newly created user to group members
IAuthenticationGroupBean marketingGroup =
authDomainBean.createGroupBean();
marketingGroup.setGroupName("Marketing");
IAuthenticationGroupBean.IGroupMembersType marketingMembers =
marketingGroup.createGroupMembers();
IAuthenticationGroupBean.IGroupMemberType groupMember =
marketingMembers.createMember();
groupMember.setMemberName("Joe");
groupMember.setMemberType("user");
marketingMembers.add("Joe", groupMember);
marketingGroup.setGroupMembers(marketingMembers);
factory.saveBean(marketingGroup);
}
}

Progress SonicMQ Administrative Programming Guide V7.5 37

Chapter 2: Using the Configuration API for the Sonic Management Environment

Create an ACL in the authentication domain, setting ACL parameters:

private static void createACL(MQMgmtBeanFactory factory) throws MgmtException

{
// Load the Authentication Domain bean
IAuthenticationDomainBean authDomainBean =
factory.getAuthenticationDomainBean(DEFAULT_AUTHENTICATION_DOMAIN);
// Load the Authorization Policy bean
IAuthorizationPolicyBean policyBean =
factory.getAuthorizationPolicyBean(DEFAULT_AUTHORIZATION_POLICY);
try
{
//create new ACL bean
IAuthorizationAclBean aclNew = policyBean.createAclBean();
aclNew.setAclType("SUBSCRIBE_ACL");
aclNew.setPrincipalName("PUBLIC");
aclNew.setPrincipalType("group");
aclNew.setResourceName("test_acl");
aclNew.setResourceType("topic");
aclNew.setPermission("GRANT");
aclNew.setAuthenticationDomain(authDomainBean);
factory.saveBean(aclNew); //throws exception if duplicate ACL exists
}
catch (MgmtException e)
{
System.out.println(e.getMessage());
}
}

Create a QoP for the authentication policy, setting QoP parameters including resource
name and type:

private static void createQop(MQMgmtBeanFactory factory) throws MgmtException

{
// Load the Authorization Policy bean
IAuthorizationPolicyBean policyBean =
factory.getAuthorizationPolicyBean(DEFAULT_AUTHORIZATION_POLICY);
try
{
//create new Qop bean
IAuthorizationQopBean qopNew = policyBean.createQopBean();
qopNew.setQop("privacy");
qopNew.setResourceName("test_qop");
qopNew.setResourceType("topic");
factory.saveBean(qopNew); //throws exception if duplicate Qop exists
}
catch (MgmtException e)
{
System.out.println(e.getMessage());
}
}

See “Security Java Sample” on page 48 and “Security JavaScript Sample” on page 51 for
information about samples that demonstrate implementing security using the
Configuration API.

38 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

Configure Certificate Revocation List Caches

A certificate revocation list (CRL) is a list of certificates that have been revoked for
whatever reason before their scheduled expiration date. When verifying a trusted
certificate’s signature, the server can review the CRL to see whether the signer’s
certificate has been revoked.
SonicMQ provides the facility to retrieve CRLs from a specified LDAP server or its
backup, and then cache the CRLs on the broker so that their content can be used. Each
CRL cache is set with a refresh interval and a lifetime (if not refreshed).
Important SonicMQ does not include the establishment and operation of LDAP servers and their
techniques for retrieval and staging of CRLs from certificate authority distribution points.

These methods in com.sonicsw.mq.mgmtapi.config interface

IAbstractBrokerBean.IAbstractSslParametersType facilitate configuration of CRLs.
They throw MgmtException when the attribute does not exist or if there is some problem
obtaining or creating this attribute.

CRL Checking

setDoCrlChecking
public void setDoCrlChecking(boolean value)
Sets the attribute for DO_CRL_CHECKING to the specified boolean value.

getDoCrlChecking
public boolean getDoCrlChecking()
Gets the attribute for DO_CRL_CHECKING as a boolean value. See also
getDoCrlCheckingMetaData() to return the IMgmtAttributeMetaData value.

CA Lists (CRL Caches)

createCaList
public IBrokerBean.ICaListType createCaList()
Creates an instance of an ICaListType attribute. This new instance is not currently part of
the configuration. Once it has been configured, set into the configuration using the
setCaList method.

setCaList
public void setCaList(IBrokerBean.ICaListType value)
Sets the attribute for CA_LIST to the specified ICaListType value.

Progress SonicMQ Administrative Programming Guide V7.5 39

Chapter 2: Using the Configuration API for the Sonic Management Environment

getCaList
public IBrokerBean.ICaListType getCaList()
Gets the attribute for CA_LIST.
See also getCaListMetaData() to get attribute metadata for CA_LIST.

Primary LDAP Server for CRLs

createPrimaryLdapServerConnectionProperties
public IBrokerBean.ILdapConnectionType
createPrimaryLdapServerConnectionProperties()
Creates an instance of an ILdapConnectionType attribute. This new instance is not
currently part of the configuration. After it is configured, set it into the configuration using
the setPrimaryLdapServerConnectionProperties method to return the new
ILdapConnectionType bean.

setPrimaryLdapServerConnectionProperties
public void setPrimaryLdapServerConnectionProperties
(IBrokerBean.ILdapConnectionType value)
Sets the attribute for PRIMARY_LDAP_SERVER_CONNECTION_PROPERTIES to the specified
ILdapConnectionType value.

getPrimaryLdapServerConnectionProperties
public void setPrimaryLdapServerConnectionProperties
(IBrokerBean.ILdapConnectionType value)
Gets the value of setPrimaryLdapServerConnectionProperties. See also
getPrimaryLdapServerConnectionPropertiesMetadata() to return the
IMgmtAttributeMetaData value.

Backup LDAP Server for CRLs

createBackupLdapServerConnectionProperties
public IBrokerBean.ILdapConnectionType
createBackupLdapServerConnectionProperties()
Creates an instance of an ILdapConnectionType attribute. This new instance is not
currently part of the configuration. After it is configured, set it into the configuration using
the setBackupLdapServerConnectionProperties method to return the new
ILdapConnectionType bean.

40 Progress SonicMQ Administrative Programming Guide V7.5

 Code Examples for the Configuration API

setPrimaryLdapServerConnectionProperties
public void setPrimaryLdapServerConnectionProperties
(IBrokerBean.ILdapConnectionType value)
Gets the value of setPrimaryLdapServerConnectionProperties. See also
getPrimaryLdapServerConnectionPropertiesMetadata() to return the
IMgmtAttributeMetaData value.

getBackupLdapServerConnectionProperties
public void setBackupLdapServerConnectionProperties
(IBrokerBean.ILdapConnectionType value)
Gets the value of setBackupLdapServerConnectionProperties. See also
getBackupLdapServerConnectionPropertiesMetadata() to return the
IMgmtAttributeMetaData value.

Disabling/Enabling the Nagle Algorithm

The Nagle algorithm allows buffering of small data before sending the data as a fully
constructed IP packet. Enabling the Nagle algorithm can help improve the performance
of your applications (see the chapter “TcpNodelay: Nagle Algorithm” in the Progress
SonicMQ Performance Tuning Guide for information about using this feature).
In SonicMQ, the Nagle algorithm is, by default, disabled. You can enable the Nagle
algorithm by setting the attribute TcpNodelay, as shown in the following code example:

import com.sonicsw.mq.mgmtapi.config.*;

// Get the broker configuration

MQMgmtBeanFactory domain= new MQMgmtBeanFactory();
//Connect to the Directory Service
domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password

// Load the Broker Bean for "/Brokers/Broker1"

IBrokerBean broker = domain.getBrokerBean("/Brokers/Broker1");
IBrokerBean.ITuningParametersType params =
broker.getConnectionTuningParameters();

// Make sure Nagle algorithm is disabled (TcpNodelay=true)

if (!params.getTcpNodelay())
{
params.setTcpNodelay(true);
}

//Save and commit changes

domain.saveBrokerBean(broker);
domain.commit();

Progress SonicMQ Administrative Programming Guide V7.5 41

Chapter 2: Using the Configuration API for the Sonic Management Environment

Using Advanced Property Names in Applications

You set advanced properties generically by name. For example,
RECOVERY_LOG_FLUSH_DELAY is an integer attribute of the IBrokerBean.IRecoveryLogType.
The following code example shows how you can set this property name:

import com.sonicsw.mq.mgmtapi.config.*;
import com.sonicsw.mq.mgmtapi.config.constants.*;

// Get the broker config

MQMgmtBeanFactory domain= new MQMgmtBeanFactory();
//Connect to the Directory Service
domain.connect("Domain1", // DS Domain
"tcp://localhost:2506", // DS Location
"Administrator", // Username
"Administrator"); // Password
// Load the Broker Bean for broker "/Brokers/Broker1".
// Then get the Recovery Log parameters
IBrokerBean broker =domain.getBrokerBean("/Brokers/Broker1");
IBrokerBean.ITuningParametersType params =
broker.getBrokerRecoveryLogParameters();
// Set the RECOVERY_LOG_FLUSH_DELAY to 0
params.setIntegerAttribute(“RECOVERY_LOG_FLUSH_DELAY”, 0);
// When done, save and commit changes
domain.saveBrokerBean(broker);
domain.commit()

Note If you type the name of an advanced property incorrectly, you get a runtime exception
when you try to set the attribute.

Configuration Names
All operations on collections, containers, brokers, clusters, queues, and routings use
logical names. These names allow you to name and organize your components into a
hierarchical structure of your choosing. The configuration name consists of the path name
and the component name. For example, the name: /Brokers/Broker1 describes a broker
configuration, Broker1, that is stored in the folder Brokers.
You must use logical names in your applications to refer to all configurations, including
containers, collections, and brokers. For example, you can define a variable for a broker
as:
private static final String BROKER_NAME = "/Brokers/Broker1"

For more information about names, see the chapter “Introduction to Configuration” in the
Progress SonicMQ Configuration and Management Guide.

42 Progress SonicMQ Administrative Programming Guide V7.5

 Using Inner Classes

Using Inner Classes

The Configuration API uses inner classes to structure parameters, lists, and tables. These
inner classes contain related components. Use get( ) and set( ) methods to access
values or components in these inner classes. Code Sample 1 shows the interface within a
broker for accessing a recovery log path.
Code Sample 1. IBrokerBean Interface
public interface IBrokerBean extends IMgmtBeanBase
{
public IBrokerBean.IRecoveryLogType getBrokerRecoveryLogParameters()
throws MgmtException;

public interface IRecoveryLogType extends IMgmtSubBeanBase

{
public String getRecoveryLogPath() throws MgmtException;
}
}

You can access maps in inner classes. The Configuration API includes methods to add and
delete from a map keyed off a name. Code Sample 2 shows the IMgmtMapBase interface.
Code Sample 2. IMgmtMapBase Interface
public interface IMgmtMapBase extends IMgmtSubBeanBase
{
public List getKeyNames() throws MgmtException;

public void add(String name, Object val) throws MgmtException;

public void delete(String name) throws MgmtException;

}

Code Sample 3, from the CreateQueues sample application, shows how to:
● Get a queue from a map
● Create a queue
● Add a queue to the queues map
● Save the bean including the new queue
● Commit the save operation

Progress SonicMQ Administrative Programming Guide V7.5 43

Chapter 2: Using the Configuration API for the Sonic Management Environment

Code Sample 3. Accessing a Queues Map

...

IQueuesBean.IQueuesSetType queues = broker.getQueuesBean().getQueues();

IQueuesBean.IQueueAttributes queue;

try
{
// check if the specified queue already exists
queue = queues.getQueue(QUEUE_NAME);

System.out.println(QUEUE_NAME + " already exists");

}
catch(MgmtException e)
{
// Queue doesn't exist - create it. It will have default values
// for all attributes

System.out.println(QUEUE_NAME + " doesn't exist. Creating it.");

queue = queues.createQueue();
queue.setQueueName(QUEUE_NAME);

// Add the new queue into the list of queues

queues.addQueue(QUEUE_NAME, queue);
}

// Print information about this queue

printQueueInfo(queue);

// Now change some of the queue values

queue.setQueueMaxSize(12345);
queue.setReadExclusive(false);

// save bean
domain.saveBrokerBean(broker);
domain.commit();

You can also access indexed lists in inner classes. The Configuration API includes
methods to add, insert, and delete from an indexed list. Code Sample 4 shows the
IMgmtListBase interface.

Code Sample 4. IMgmtListBase Interface

public interface IMgmtListBase extends IMgmtSubBeanBase
{
public int getCount() throws MgmtException;

public void add(Object val) throws MgmtException;

public void insert(int index, Object val) throws MgmtException;

public void delete(int index) throws MgmtException;

}

44 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Configuration API Samples

Sonic Configuration API Samples

SonicMQ provides sample applications to help you get started with the Configuration
API. These samples are included in your SonicMQ installation, and located in the
management configuration samples directory at:
MQ7.5_install_root\samples\Management\configAPI\

The following subdirectories provide java and JavaScript Configuration API samples:
● javaConfigBean — A Java example showing how to configure the Sonic Management
Environment using the Configuration APIs
● jsConfigBean — A JavaScript example showing how to configure the Sonic
Management Environment using the Configuration APIs
These directories contain scripts that run the samples or configure the environment in
which to run the samples.
All samples directories have a readme.txt that describes the contents more completely.
Where appropriate, the readme.txt file contains instructions for running more complex
samples.

Java Configuration Samples

The Java Configuration API samples are located in the directory
MQ7.5_install_root\samples\Management\configAPI\javaConfigBean. This directory
includes the following Java samples:
● CreateQueues.java — Create and modify queues
● CreateRoutes.java — Create and modify routings
● CreateCollection.java — Create collections
● CreateContainer.java — Create a container
● SecuritySample.java — Create a user, group, access control list (ACL), and
quality of protection (QoP)
● HiddenAttribute.java — Set and get a hidden attribute

Each sample is described in more detail in the following sections. These samples are
based on a typical installation of SonicMQ where the default settings were accepted, such
as domain name, container name, and broker port. If you have different settings, you must
change the sample code accordingly and recompile.

Important To execute the javaConfigBean sample you must install the SonicMQ container.

Progress SonicMQ Administrative Programming Guide V7.5 45

Chapter 2: Using the Configuration API for the Sonic Management Environment

◆ To run the javaConfigBean samples:

1. Start the default broker for the SonicMQ container:
Start > Programs > Progress Sonic > SonicMQ 7.5 > SonicMQ DomainManager
2. Open a console window to the following directory:
MQ7.5_install_root\samples\Management\configAPI\javaConfigBean

Note Equivalent JavaScript-based samples can be found in the directory:

MQ7.5_install_root\samples\Management\configAPI\jsConfigBean

3. Enter the appropriate command for your platform.

■ For Windows, enter:
..\..\..\Mgmt sample_classname
■ For UNIX/Linux, enter:
sh ../../../Mgmt.sh sample_classname

Important The command files for administrative applications specifically set the command line to
launch the JRE with the directive -Xbootclasspath/p: explicitly identifying
xercesImpl.jar, and xmlParserAPIs.jar

When you create launch scripts for your applications, be sure to include these
bootclasspath settings as well as the environment and classpath settings.

4. Start the Sonic Management Console:

Start > Programs > Progress Sonic > SonicMQ 7.5 > Management Console
You can check the Sonic Management Console to confirm that the samples execute
properly as you run the following procedures.

Create Queues Java Sample

The CreateQueues class demonstrate using Java to:
● Load BrokerBean
● Get a list of queues containing all queue information from the broker
● Create a queue and modify some queue parameters
Run CreateQueues.java to create the queue NewQueue1. The console window displays
informative messages about the queue created by this sample.
In the Sonic Management Console, select the Configure tab and select
Brokers\Broker1\Queues to see NewQueue1 (you might need to Refresh the view).

46 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Configuration API Samples

Create Routes Java Sample

The CreateRoutes class demonstrates using Java to:
● Load BrokerBean.
● Get a list of routings from the broker.
● Create a routing definition and modify some of its parameters.
Run CreateRoutes.java to create an HTTP Soap routing named Test1. The console
window displays informative messages about the route created by this sample.
In the Sonic Management Console, select the Configure tab and select
Brokers\Broker1\Routing\Definitions to see the new routing definition listed. You might
need to select Refresh to show the new routing.

Create Collection Java Sample

The CreateCollection class demonstrates using Java to:
● Create a component collection.
● Create a container collection.
Run CreateCollection.java to create the component collection named
ComponentCollection and the container collection named ContainerCollection. The
console window displays informative messages about the collections created by this
sample.
In the Sonic Management Console, select the Configure tab and select the Collections
folder to see these collections. You might need to select Refresh to show the collections.

Create Container Java Sample

The CreateContainer script demonstrates using Java to:
● Check if a container already exists with the same name.
● Create a new container and specify a name and attribute values.
Run CreateContainer.java to create the container named NewContainer. The console
window displays informative messages about the container created by this sample.
In the Sonic Management Console, select the Configure tab and select the Containers
folder to see the new container. You might need to select Refresh to show the container.

Progress SonicMQ Administrative Programming Guide V7.5 47

Chapter 2: Using the Configuration API for the Sonic Management Environment

Security Java Sample

The SecuritySample class demonstrates using Java to:
● Create a user in the default authentication domain.
● Create a Group in the default authentication domain.
● Create an access control list (ACL) in the default authorization policy.
● Create a quality of protection (QoP) setting in the default authorization policy.
Run SecuritySample.java to create:
● The user Joe and the group Marketing
On the Configure tab of the Sonic Management Console, select the
Security/Default Authentication folder, then look at the Groups and the Users. You
might need to select Refresh to show the new entries.
● The ACL test_acl and QoP setting test_qop
On the Configure tab of the Sonic Management Console, select the
Security/Default Policies folder, then look at the ACLs and the QoP. You might need
to select Refresh to show the new entries.

Hidden Attribute Java Sample

The HiddenAttribute class demonstrates using Java to:
● Use the Configuration API to set and retrieve the value of a hidden attribute.
Execute HiddenAttribute.java to:
● Retrieve the value of the parameter TXN_FLUSH_THREADS_ATTR
● Set the value of TXN_FLUSH_THREADS_ATTR to 2
To verify that the hidden attribute has been set, select the Configure tab of the Sonic
Management Console, right-click the Brokers\Broker1 node and select Properties. In the
Edit Broker Properties dialog box that opens, select the Advanced tab, then click Edit...
next to Edit advanced properties for this Broker configuration. The Edit Advanced
Properties dialog box shows the value you set for TXN_FLUSH_THREADS_ATTR when you ran
HiddenAttribute.java.

48 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Configuration API Samples

JavaScript Configuration Samples

The JavaScript Configuration API samples are located in the directory
MQ7.5_install_root\samples\Management\configAPI\jsConfigBean. This directory
includes the following JavaScript samples:
● CreateQueue.js — Create and modify queues.
● CreateRoutes.js — Create and modify routings.
● CreateCollection.js — Create collections.
● CreateContainer.js — Create a container.
● SecuritySample.js — Create user, group, access control list (ACL), and quality of
protection (QoP).
● HiddenAttribute.js — Set and get hidden attributes.
● Common.js — Contains utility functions used by these samples.

Important To execute the jsConfigBean sample you must have installed the SonicMQ container.

Each sample script is described in more detail in the following sections. These samples
are based on a typical installation of SonicMQ where the default settings were accepted,
such as domain name, container name, and broker port. If you have different settings, you
must change the sample code accordingly and recompile.

◆ To run the jsConfigBean samples:

1. Start the default broker for the SonicMQ container:
Start > Programs > Progress Sonic > SonicMQ 7.5 > SonicMQ DomainManager
2. Open a console window to the following directory:
MQ7.5_install_root\samples\Management\configAPI\jsConfigBean

3. Enter the appropriate command for your platform.

■ For Windows, enter ..\..\..\jsRun scriptfile.js
■ For UNIX or Linux, enter sh ../../../jsRun.sh scriptfile.js
Note Equivalent Java-based samples can be found in the directory:
MQ7.5_install_root\samples\Management\configAPI\javaConfigBean

4. Start the Sonic Management Console:

Start > Programs > Progress Sonic > SonicMQ 7.5 > Management Console
You can check the Sonic Management Console to confirm that the samples execute
properly as you run the following procedures.

Progress SonicMQ Administrative Programming Guide V7.5 49

Chapter 2: Using the Configuration API for the Sonic Management Environment

Create Queue JavaScript Sample

The CreateQueue script demonstrates using JavaScript to:
● Load BrokerBean.
● Get a list of queues containing all queue information from the broker.
● Create a queue and modify some queue parameters.
Execute CreateQueue.js to create the queue NewQueue1. The console window displays
informative messages about the queue created by this sample.
In the Sonic Management Console, select the Configure tab and select
Brokers\Broker1\Queues to see NewQueue1 (you might need to Refresh the view).

Create Routes JavaScript Sample

The CreateRoutes script demonstrate using JavaScript to:
● Load BrokerBean.
● Get a list of routings from the broker.
● Create routing definition and modify some of its parameters.
Execute CreateRoutes.js to create an HTTP Soap routing named Test1. The console
window displays informative messages about the route created by this sample.
In the Sonic Management Console, select the Configure tab and select
Brokers\Broker1\Routing\Definitions to see the new routing definition listed. You might
need to select Refresh to show the new routing.

Create Collection JavaScript Sample

The CreateCollection script demonstrates using JavaScript to:
● Create a component collection.
● Create a container collection.
Execute CreateCollection.js to create the component collection named
ComponentCollection and the container collection named ContainerCollection. The
console window displays informative messages about the containers created by this
sample.
In the Sonic Management Console, select the Configure tab and select the Collections
folder to see these collections. You might need to select Refresh to show the collections.

50 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Configuration API Samples

Create Container JavaScript Sample

The CreateContainer script demonstrates using JavaScript to:
● Check if a container already exists with the same name.
● Create a new container and specify a name and attribute values.
Execute CreateContainer.js to create the container named NewContainer. The console
window displays informative messages about the container created by this sample.
In the Sonic Management Console, select the Configure tab and select the Containers
folder to see the new container. You might need to select Refresh to show the container.

Security JavaScript Sample

The SecuritySample script demonstrates using JavaScript to:
● Create a user in the default authentication domain.
● Create a group in the default authentication domain.
● Create an access control list (ACL) in the default authorization policy.
● Create a quality of protection (QoP) setting in the default authorization policy.
Execute SecuritySample.js to create:
● The user Joe Smith and the group Marketing
On the Configure tab of the Sonic Management Console, select the
Security/Default Authentication folder, then look at the Groups and the Users. You
might need to select Refresh to show the new entries.
● The ACL test_acl and QoP setting test_qop
On the Configure tab of the Sonic Management Console, select the
Security/Default Authorization folder then look at the ACLs and the QoP. You might
need to select Refresh to show the new entries.

Progress SonicMQ Administrative Programming Guide V7.5 51

Chapter 2: Using the Configuration API for the Sonic Management Environment

Hidden Attribute JavaScript Sample

The HiddenAttribute script demonstrates using JavaScript to:
● Use the Configuration API to set and retrieve the value of a hidden attribute.
Execute HiddenAttribute.js to:
● Retrieve the value of the parameter TXN_FLUSH_THREADS_ATTR
● Set the value of TXN_FLUSH_THREADS_ATTR to 3
To verify that the hidden attribute has been set, select the Configure tab of the Sonic
Management Console, right-click the Brokers\Broker1 node and select Properties. In the
Edit Broker Properties dialog box that opens, select the Advanced tab, then click Edit...
next to Edit advanced properties for this Broker configuration. The Edit Advanced
Properties dialog box shows the value you set for TXN_FLUSH_THREADS_ATTR when you ran
HiddenAttribute.java.

52 Progress SonicMQ Administrative Programming Guide V7.5

Chapter 3 Using the Runtime API for the Sonic
Management Environment

Chapter 3 describes using the SonicMQ Runtime API, which provides programmatic
access to the Sonic Management Environment. This chapter contains the following
sections:
● “Overview of the Runtime API” — Explains the option of using the JMX APIs or the
Proxy APIs in your runtime programming
● “Manageable Components in the Runtime API” — Explains various Sonic
components using the Runtime API
● “Management Attributes” — Describes component management attributes associated
with runtime configuration and behavior
● “Management Operations” — Describes management operations for runtime actions
that a component can perform
● “Metrics” — Describes metrics and alerts exposed by the broker and agent in the
Sonic Management environment
● “Management Notifications” — Describes metric alert notifications available for
manageable components in the Runtime API
● “Filtering Notifications” — Explains how to access sample applications to help you
get started with the Runtime API

Progress SonicMQ Administrative Programming Guide V7.5 53

Chapter 3: Using the Runtime API for the Sonic Management Environment

Overview of the Runtime API

The Runtime API provides a programming interface that enables you to monitor and
manage running containers and components in your own management applications.
Runtime management allows you to gather runtime information and perform operations
on manageable entities (containers, components) in the Sonic environment, providing:
● An open way to interrogate the components to determine their specific attributes,
operation and notifications
● A dynamic way to view or change, invoke, and listen for the attributes, operations,
and notifications
The Runtime API exposed by Sonic containers and components is expressed as:
● Attributes — Settings associated with a component's runtime configuration and
status
● Operations — Runtime actions that a component can perform
● Notifications — Published by component when significant events occur

Programming Options
You can program using either:
● JMX APIs— Reflective/dynamic style interface based on JMX interfaces presented
through a JMS/JMX Connector Client
● Proxy APIs — Simplified programming through a typed/static style interface

54 Progress SonicMQ Administrative Programming Guide V7.5

 Overview of the Runtime API

As shown in Figure 1, the proxy APIs provide an interface that masks the complexity of
the JMS/JMX connector client.

Management Application or Script

Proxies

JMS/JMX Connector Client

Figure 1. Proxies and JMS/JMX Connector Client

The following sections discuss these two programming options.

JMX APIs
The JMS/JMX Connector Client provides a remote interface to the JMX MBean Servers
located in each container. The connector follows a similar pattern to other JMX
connectors in the public domain, however it has the following advantages:
● A single connector can be used to address any container and its components
(MBeans) within a domain; this is achieved through the JMX domain and MBean
naming patterns used by the Sonic Management Environment.
● The connector is built on the SonicMQ messaging transport and thus provides a high
level of reliability for management communications and many options for securing
such communications (even across the Internet and through firewalls).
● The connector transparently handles short term transient connection failures and
provides a configurable request timeout mechanism.

Progress SonicMQ Administrative Programming Guide V7.5 55

Chapter 3: Using the Runtime API for the Sonic Management Environment

Code Sample 5 shows the JMX pattern for creating a connector through the use of a
connector address object.
Code Sample 5. Creating a JMS Connector Client
Hashtable env = new Hashtable( );
env.put(“ConnectionURLs", "tcp://localhost:2506");
env.put("DefaultUser", "Administrator");
env.put("DefaultPassword", "Administrator");
JMSConnectorAddress address = new JMSConnectorAddress(env);
JMSConnectorClient connector = new JMSConnectorClient( );
connector.connect(address)
..
connector.disconnect( );

Note The Proxy APIs require creation of a connector, although all subsequent programming is
done through the proxy interface (see “Sonic Proxy APIs” on page 57).

The connector has two modes, one that allows the connector to communicate to all JMX
MBean Servers and another that dedicates a connector to a single JMX MBean Server
(equivalent to a Sonic Management Environment container). To support the former
(default) mode, certain MBeanServer methods are not supported on the connector when
in this mode. The unsupported methods are those that do not take a JMX ObjectName in
their parameter list and thus cannot take advantage of the JMX domain and MBean
naming patterns used by the Sonic Management Environment.
See the Runtime API online documentation for information about the connector address.
This documentation is located at sonic_install_root/Docs7.5/api/mgmt_api/index.html in
the package com.sonicsw.mf.jmx.client.
The following naming pattern is used by the Sonic Management Environment to uniquely
address a component:
sonicdomain.container:ID=component

which maps to JMX ObjectName objects as follows:

sonicdomain.container -> JMX MBeanServer domain
ID=component -> JMX MBean key property (key=value)
For example:

ObjectName brokerName = new ObjectName(“Domain1.Container1:ID=Broker1”);

56 Progress SonicMQ Administrative Programming Guide V7.5

 Overview of the Runtime API

The JMX API provides runtime programming access in the following ways:
● Attributes — Use get and set methods by attribute name.
● Operations — Invoke methods by name and signature.
● Notifications — Add and remove subscriptions to notifications.

To determine the attributes, operations, and notifications exposed by a component

(MBean) you can either:
● Obtain the MBeanInfo (management outerface meta-data) for the component through
the getMbeanInfo( ) method on the connector.
● Refer to the appropriate proxy API documentation
(see sonic_install_root/Docs7.5/api/mgmt_api/index.html).
Code Sample 6 shows how you can use the JMX API.
Code Sample 6. Using the JMX API
..
ArrayList connections =
(ArrayList)connector.invoke(brokerName,
“getConnections”,
new Object[]{ null },
new String[]{ String.class.getName() });
..
Attribute traceAttribute = new Attribute(“TraceMask” new Integer(5));
connector.setAttribute(brokerName, traceAttribute);

For a sample application that uses the JMX API, see “JMX DynamicMBean Sample” on
page 78. For information about the JMX interface and JMX connectors, see the JMX 1.2
documentation available from the Sun Web site at:
http://java.sun.com/products/JavaManagement/

Sonic Proxy APIs

The Runtime API provides programmatic access via proxies to runtime attributes,
operations, and notifications for the agent, agent manager, activation daemon, and broker.
The Runtime API includes the following packages and proxy interfaces:
The package com.sonicsw.mf.mgmtapi.runtime includes the interfaces:
● IAgentProxy
● IAgentManagerProxy
● IActivationDaemonProxy
● ICollectionsMonitorProxy
● IDirectoryServiceProxy

Progress SonicMQ Administrative Programming Guide V7.5 57

Chapter 3: Using the Runtime API for the Sonic Management Environment

The package com.sonicsw.mq.mgmtapi.runtime includes the interface:

● IBrokerProxy

The proxy APIs provide runtime programming access in the following ways:
● Attributes — Get and set attributes by name:
❍ attributeType getattributeName
❍ attributeType setattributeName
● Operations — Invoke methods by name and signature. For example, void shutdown()
● Notifications — Add and remove subscriptions to notifications

The proxy APIs can be used in custom Java applications or called from scripting
languages that support Java objects such as JavaScript.
The Runtime API provides factories to create the proxy implementations of the agent,
agent manager, activation daemon, collections monitor, Directory Service, and broker
interfaces. See the Runtime API online documentation for detailed information about
factories, interfaces, classes, and methods. This documentation is located at:
sonic_install_root/Docs7.5/api/mgmt_api/index.html.

Code Sample 7 shows the required use of a factory to create a proxy.

Code Sample 7. Using the Proxy API
// Bind a proxy to a specific runtime name; in this example, bind the brokerProxy
// to a specific brokerName

IBrokerProxy brokerProxy =
MQProxyFactory.createBrokerProxy(connector, brokerName);
..
// Typed interface allows method to return an array list without casting

ArrayList connections = brokerProxy.getConnections(null);

..
brokerProxy.setTraceMask(5);

For sample applications that use the proxy APIs, see “Java Proxy API Samples” on
page 85 and “JavaScript Proxy API Samples” on page 89. These samples provide both
Java and JavaScript programming examples.

58 Progress SonicMQ Administrative Programming Guide V7.5

 Manageable Components in the Runtime API

Manageable Components in the Runtime API

The following sections explain how to manage the agent, agent manager, activation
daemon, collections monitor, Directory Service, and broker components using the
Runtime API.
For each JMX MBean attribute, the Runtime API provides an associated
getattributeName method (for readable attributes) and/or a setattributeName method (for
writable attributes). For each JMX MBean operation, the Runtime API provides an
associated method with a signature as described by the MBean's operation meta-data.
Each JMX MBean operation has an associated impact:
● ACTION — Indicates that the operation is a write-like and would modify the MBean
in some way, typically by writing some value or changing a configuration
● INFO — Indicates that the operation is read-like and basically returns information
● ACTION/INFO — Indicates that the operation is both read-like and write-like
● UNKNOWN — Indicates that the operation has an unknown nature

All exceptions emitted by implementations are wrapped as a ProxyRuntimeException.

Agent
The agent component provides an API to manage a container and is synonymous with the
container in this discussion. Each container hosts exactly one agent component. The
IAgentProxy is a remote interface to a runtime instance of an agent. Management
attributes and operations are documented in this interface. See the Runtime API online
documentation at: sonic_install_root/Docs7.5/api/mgmt_api/index.html for more
information about the IAgentProxy interface, located in the package
com.sonicsw.mf.mgmtapi.runtime.

An implementation of this interface can be created using the MFProxyFactory class. Each
implementation instance is valid for the life of the provided JMS/JMX connector and
MBean ObjectName. The implementation is built using remote JMX MBeanServer calls.
For more information about JMX, see the following:
● Sun’s JMX specification available from the Sun Web site at:
http://java.sun.com/products/JavaManagement/
● Sonic Runtime API online documentation available at:
sonic_install_root/Docs7.5/api/mgmt_api/index.html

Progress SonicMQ Administrative Programming Guide V7.5 59

Chapter 3: Using the Runtime API for the Sonic Management Environment

Agent Manager
The agent manager provides a central point of access to manage the operational aspects
of the whole domain. The agent manager maintains the current runtime status of the whole
domain in two ways:
● After determining an initial state for each container in the domain, the agent manager
applies updates to the aggregated state as it receives state change notifications from
individual containers.
● The agent manager periodically polls each container for its status.
When the agent manager cannot contact a container, the container's status is assumed to
be offline. The agent manager may fail to contact the container due to container failure,
the fact that the container was never started, or due to a long-term communications failure.
The polling interval can be configured for each container so that no polling occurs or so
that each container is polled at a configured interval. If polling is not enabled, it is possible
the agent manager will not detect some container failures (those that prevent state change
notifications from being sent, such as a crash of the host machine on which the container
is running).
A single agent manager component (or fault tolerant pair) is allowed for a given domain.
The Sonic Management Console allows configuration of a single container in the domain
to host the agent manager component (or a container for each of the recovery and backup
agent managers for the deployment of a fault tolerant pair).
The public interface IAgentManagerProxy is a remote interface to the agent manager
runtime instance. Management attributes and operations are documented in this interface.
See the Runtime API online documentation at
sonic_install_root/Docs7.5/api/mgmt_api/index.html for more information about the
IAgentManagerProxy interface, located in the package com.sonicsw.mf.mgmtapi.runtime.

An implementation of the IAgentManagerProxy interface can be created using the

MFProxyFactoryclass. Each implementation instance is valid for the life of the provided
JMS/JMX connector and MBean ObjectName. The implementation is built using remote
JMX MBeanServer calls.

60 Progress SonicMQ Administrative Programming Guide V7.5

 Manageable Components in the Runtime API

Activation Daemon
An Activation Daemon provides a way to launch new child containers as spawned
processes of the container hosting the Activation Daemon. This allows new containers to
be launched by remote administrative clients without the administrator having to log on
to that host. A typical use would be to have the container hosting the Activation Daemon
launched as a Windows service on Windows platforms or a startup process under
UNIX/Linux.
An Activation Daemon monitors the health of its child 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 (see the Progress SonicMQ
Configuration and Management Guide), or through the Management API
The public interface IActivationDaemonProxy is a remote interface to a runtime instance
of an ActivationDaemon. Management attributes and operations are documented in this
interface. See the Runtime API online documentation at Docs7.5/api/mgmt_api for more
information about the IActivationDaemonProxy interface, located in the package
com.sonicsw.mf.mgmtapi.runtime.

An implementation of the IActivationDaemonProxy interface can be created using the

MFProxyFactory class. Each implementation instance is valid for the life of the provided
JMS/JMX connector and MBean ObjectName. The implementation is built using remote
JMX MBeanServer calls.

Collections Monitor
A collections monitor provides a mechanism to monitor and record runtime information
across collections of components. In particular, a collections monitor can be configured to:
● Forward notification generated by the components in a collection
● Store and aggregate notifications generated by the components in a collection
● Store and aggregate metrics supplied by the components in a collection

Progress SonicMQ Administrative Programming Guide V7.5 61

Chapter 3: Using the Runtime API for the Sonic Management Environment

The management API exposed by the collections monitor allows access to both
aggregated monitoring information and the underlying history used to generate the
aggregated data.
The public interface ICollectionsMonitorProxy is a remote interface to the collections
monitor instance. Management attributes and operations are documented in this interface.
See the Runtime API online documentation at
sonic_install_root/Docs7.5/api/mgmt_api/index.html for more information about the
ICollectionsMonitorProxy interface, located in the package
com.sonicsw.mf.mgmtapi.runtime.

An implementation of this interface can be created using the MFProxyFactory class. Each
implementation instance is valid for the life of the provided JMS/JMX connector and
MBean ObjectName. The implementation is built using remote JMX MBeanServer calls.

Directory Service
The Directory Service provides a service through which you can configure a Sonic
deployment and manage the storage of the configuration information. Although these two
aspects are exposed through the management API of the Directory Service, an additional
API, the Configuration API (see Chapter 2, “Using the Configuration API for the Sonic
Management Environment”), is used to hide the complexities of configuration and the
schema of the underlying configuration store. However, the operational aspects of the
Directory Service (for example, taking storage backups and controlling fault tolerant
behavior) are provided in the IDirectoryServiceProxy interface.
The public interface IDirectoryServiceProxy is a remote interface to a runtime instance
of a DirectoryService. Management attributes and operations are documented in this
interface. See the Runtime API online documentation at
sonic_install_root/Docs7.5/api/mgmt_api/index.html for more information about the
IDirectoryServiceProxy interface, located in the package
com.sonicsw.mf.mgmtapi.runtime.

An implementation of the IDirectoryServiceProxy interface can be created using the

MFProxyFactoryclass. Each implementation instance is valid for the life of the provided
JMS/JMX connector and MBean ObjectName. The implementation is built using remote
JMX MBeanServer calls.

62 Progress SonicMQ Administrative Programming Guide V7.5

 Management Attributes

Broker
The public interface IBrokerProxy is a remote interface to a runtime instance of a
SonicMQ broker. Management attributes and operations are documented in this interface.
See the Runtime API online documentation at
sonic_install_root/Docs7.5/api/mgmt_api/index.html for more information about the
IBrokerProxy interface, located in the package com.sonicsw.mq.mgmtapi.runtime.

An implementation of the IBrokerProxy interface can be created using the MQProxyFactory

class. Each implementation instance is valid for the life of the provided JMS/JMX
connector and MBean ObjectName. The implementation is built using remote JMX
MBeanServer calls.
Note Using the Management API to Update a Broker’s CRL caches — There are runtime
methods for refreshing Certificate Revocation Lists (CRLs). The CRLs are accessed from
an intermediate LDAP store of Certificate Authority (CA) distribution lists.
● Force a CRL cache flush and update for the specified certificate:
ForceCRLUpdate(String CA_name)
● Gets the defined CRL lists for the broker:
String getCRLList()

Management Attributes
All components have management attributes with settings associated with the component
and its runtime configuration and behavior.
Management attributes can have some or all of the following features:
● Provide an initial value based on a component's configuration that is stored in the
Directory Service
● Be readable via the component's Runtime API
● Be settable via the component's Runtime API, so that when the value is reset, the
component's behavior will change appropriately at that time
● Be settable via dynamic changes to the component's configuration stored in the
Directory Service that are then propagated by the Directory Service to the component
If an attribute value is settable via the Runtime API, that change is transient. The next time
the component is loaded, the value is set to either its default initial value or, if appropriate,
its configuration value.

Progress SonicMQ Administrative Programming Guide V7.5 63

Chapter 3: Using the Runtime API for the Sonic Management Environment

Dynamic configuration changes that store an attribute value in the Directory Service, and
that are subsequently propagated to and handled by the component, will overwrite an
transient attribute value set through the Runtime API.
The following table summarizes management attributes available for the agent, agent
manager, activation daemon, collections monitor, Directory Service, and broker, as well
as additional attributes available for the agent and broker. See the Runtime API online
documentation for complete summaries and descriptions of operations available in each
interface, located at: sonic_install_root/Docs7.5/api/mgmt_api/index.html.

Component Attributes Available

Agent, ● Component information including Classname , Classpath,
Agent Manager, ConfigID and ReleaseVersion
Activation Daemon, ● Runtime information about the component including State ,
Collections Monitor, StateString, and Uptime
Directory Service, and ● The SharedNamespace attribute, if specified in the component’s
Broker configuration
● The trace mask attributes TraceMask and TraceMaskValues
● Error description and severity levels including LastError,
LastErrorLevel, and LastErrorLevelString

Agent ● CommandLine flag to indicate whether local command line

Package: interface is available
com.sonicsw.mf.mgmtapi.runtime ● The HostName for the container
Interface: ● Information about the log file including size and threshold
IAgentProxy ● The maximum and minimum number of threads that can be set

Agent Manager ● Fault tolerance settings (including role and state)

Collections Monitor ● The value of the HistoryDurationHours attribute

Package: ● Values of the SaveMonitoredNotifications and
com.sonicsw.mf.mgmtapi.runtime SaveThresholdNotifications attributes

Interface:
ICollectionsMonitorProxy

64 Progress SonicMQ Administrative Programming Guide V7.5

 Management Attributes

Component Attributes Available

Directory Service ● Fault tolerance settings (including role, state, and allow failover
Package: option)
com.sonicsw.mf.mgmtapi.runtime ● The status of the last backup
Interface:
IDirectoryServiceProxy

Broker ● Names of the broker, cluster, routing node

Package: ● Flag indicating whether security is enabled
com.sonicsw.mq.mgmtapi.runtime ● Metrics refresh and collection intervals
Interface:
IBrokerProxy

Progress SonicMQ Administrative Programming Guide V7.5 65

Chapter 3: Using the Runtime API for the Sonic Management Environment

Management Operations
All components have management operations that describe runtime actions that a
component can perform.
The following table summarizes management operations available for the agent, agent
manager, activation daemon, collections monitor, Directory Service, and broker. See the
Runtime API online documentation for complete summaries and descriptions of
operations available in each interface. This documentation is located at:
sonic_install_root/Docs7.5/api/mgmt_api/index.html.

Component Operations Available

Agent ● Shut down a container (by first stopping and unloading all
Package: components and then exiting)
com.sonicsw.mf.mgmtapi.runtime ● Reload an existing component
Interface: ● Get the runtime state of the agent's container and all the
components it hosts
IAgentProxy
● Save and clear the log file
● Clear any error condition reported by the agent
● Enable, disable, and gather container metrics and alerts

Agent Manager ● Change the agent manager’s state to online or offline

Package: ● Get the current runtime status of containers (and their components)
com.sonicsw.mf.mgmtapi.runtime in the domain
Interface: ● Perform an operation or set attributes across collections of
containers or components.
IAgentManagerProxy
● Clear any error condition reported by the agent
● Control fault tolerance behavior

Activation Daemon ● Change the activation daemon’s state to online or offline

Package: ● Get current runtime status of spawned components
com.sonicsw.mf.mgmtapi.runtime ● Clear any error condition reported by the activation daemon
Interface:
IActivationDaemonProxy

66 Progress SonicMQ Administrative Programming Guide V7.5

 Management Operations

Component Operations Available

Collections Monitor ● Change the collections monitor’s state to online or offline
Package: ● Get metadata for the metrics and notifications being monitored
com.sonicsw.mf.mgmtapi.runtime ● Get a list of collections being monitored
Interface: ● Get aggregated metrics for a collection, based on recorded metrics
ICollectionsMonitorProxy of a specified time window
● Get historical data for monitored metrics and notifications
● Clear any error condition reported by this monitor
● Clear all notification or metric history maintained by this monitor

Directory Service ● Clear any existing error condition.

Package: ● Set trace mask
com.sonicsw.mf.mgmtapi.runtime ● Start backup of the Directory Service store
Interface: ● Set the allow-failover option
IDirectoryServiceProxy

Broker ● Change the broker’s state to online or offline

Package: ● Enable, disable, and gather broker metrics and alerts
com.sonicsw.mq.mgmtapi.runtime ● Observe/manage queues, connections, subscriptions, routings, and
Interface: transactions
IBrokerProxy ● Clear any error condition reported by the broker

Progress SonicMQ Administrative Programming Guide V7.5 67

Chapter 3: Using the Runtime API for the Sonic Management Environment

Metrics
A metric is an interpretation of a statistic. There can be multiple interpretations of a single
set of statistical data such as, total, average, maximum, and minimum. A metric is a single
value at an instance in time calculated from raw statistical data, for example, a counter, or
a rate per second calculated over a collection interval.
Metrics are exposed by components managed within the Sonic Management environment.
The following components expose metrics:
● Agent
● SonicMQ Broker
Metrics can be selectively and dynamically enabled and disabled at runtime (enabling is
maintained across container restarts). A certain amount of overhead (depending on the
particular metric) is associated with statistical data collection and metric interpretation.
To minimize overhead, all metrics are disabled by default.
Metrics can be enabled, disabled, and gathered using either the Sonic Management
Console or the Runtime API.
Metrics are classified into trees of related metric types. Each metric's path in the tree is
represented using a list of strings, where each token describes a branch or leaf. The
canonical form of the path is displayed as a period (.) delimited list, for example:
"system.memory.CurrentUsage".

Instance Metrics
Instance metrics are used to apply the same data collection and interpretation to multiple
instances of similar entities maintained by a component. For example, the SonicMQ
broker provides instance metrics for queues and connections.
Instance metrics can be dynamically enabled and disabled at runtime for specific
instances or instances that match a common pattern (for example,
"queue.messages.Count.SampleQ*"). This allows for gathering metrics pertaining to
specific entities of interest.
Enabling instance metrics does not require that a particular entity be present at the time
of metric enabling. For example, the SonicMQ broker exposes instance metrics for
connections, and metrics for a particular connection identity can be enabled prior to the
establishment of that particular connection identity (no data collection overhead will be
incurred until the connection is established).

68 Progress SonicMQ Administrative Programming Guide V7.5

 Metrics

Alerts
Certain metrics allow alerts to be defined for the purpose of asynchronous notification
when their associated thresholds are exceeded. Which metrics allow alerts to be specified
is documented in a particular component type's documentation. For example, the
SonicMQ broker allows alerts to be specified for the rate of messages delivered to a
particular connection identity.
The term used for the notification generated as a result of a threshold having been
exceeded is an alert notification. Alert notifications are named based on their source
metric, for example, application.alert.connection.messages.ReceivedPerSecond. These
notifications encapsulate the actual value of the metric and the time the threshold was
exceeded.
Where alerts are allowed, multiple alerts may be specified. Additionally some metrics
allow definition of both high and low threshold alerts with different threshold values.

Progress SonicMQ Administrative Programming Guide V7.5 69

Chapter 3: Using the Runtime API for the Sonic Management Environment

Metrics Summary
The following table summarizes the metrics available in the agent and broker interfaces:

Component Metrics
Agent ● Memory usage
Package: ● Management thread pool
com.sonicsw.mf.mgmtapi.runtime
Interface:
IAgentProxy

Broker ● Message traffic (brokerwide or per connection or queue)

Package: ● Connection activity
com.sonicsw.mq.mgmtapi.runtime ● Queue usage (per queue)
Interface: ● Size of durable subscription store
IBrokerProxy ● Connection reject rate

Note The collections monitor interface provides aggregate metrics for a selected collection of
brokers. See the interfaceICollectionsMonitorProxy in the package
com.sonicsw.mf.mgmtapi.runtime.

Note Broker queue metrics are provided for the system queue SonicMQ.routingQueue but not for
the system queue SonicMQ.deadMessage. You can workaround that constraint by having
applications specify user-defined dead message queues. See the chapter
“Guaranteeing Messages” in the Progress SonicMQ Application Programming Guide for
more information.

See the Runtime API online documentation for complete summaries and descriptions of
metrics available in each interface. This documentation is located at:
sonic_install_root/Docs7.5/api/mgmt_api/index.html.

70 Progress SonicMQ Administrative Programming Guide V7.5

 Management Notifications

Management Notifications
Management notifications are published when significant events occur. To receive alert
notifications, your application must have metrics enabled and thresholds defined for the
notification you want to receive (see “Metrics” on page 68).
Management notifications are published by the following components:
● Agent
● Agent Manager
● Activation Daemon
● Collections Monitor
● Directory Service
● SonicMQ Broker
A notification encapsulates information about a significant event that has occurred during
the execution of a container or a component. The notification includes:
● Type of notification
● Source of the notification
● Time the notification was generated
● Attributes describing details about the event that generated the notification
Notifications are received by management clients once they have subscribed to them on a
particular component. You can subscribe to and view notifications using either the Sonic
Management Console or the Runtime API.
Notifications are classified into trees of related types. Each notification's path in the tree
is represented using a list of strings, where each token describes a branch or leaf. The
canonical form of the path is displayed as a period (.) delimited list. For example:
system.state.Online.

Metric Alert Notifications

Certain metrics allow alerts to be defined for the purpose of asynchronous notification
when their associated thresholds are exceeded. Which metrics allow alerts to be specified
is documented in a particular component type's documentation. For example, the
SonicMQ broker allows alerts to be specified for the messages delivered to a particular
connection identity.

Progress SonicMQ Administrative Programming Guide V7.5 71

Chapter 3: Using the Runtime API for the Sonic Management Environment

A notification generated as a result of an alert threshold having been exceeded is called

an alert notification. Alert notifications are named based on their source metric (for
example, application.alert.connection.messages.ReceivedPerSecond ) and encapsulate
the value of the metric and the time the threshold was exceeded.
Where alerts are allowed, multiple alerts with different values can be specified.
Additionally, some metrics allow definition of alerts with both high and low thresholds.

Notifications Summary
The following table summarizes notifications available for the agent, agent manager,
activation daemon, collections monitor, Directory Service, and broker. See the Runtime
API online documentation for complete summaries and descriptions of notifications
available in each interface. This documentation is located at:
sonic_install_root/Docs7.5/api/mgmt_api/index.html.

Important Metrics must be enabled and alert thresholds defined in order to receive alert
notifications. See “Metrics” on page 68.

Component Notifications
Agent ● Container state
Package: ● Component loading (other than startup)
com.sonicsw.mf.mgmtapi.runtime ● Trace log status
Interface: ● Metric alerts
IAgentProxy

Agent Manager ● Agent manager state

Package: ● Container state (for other containers in the domain)
com.sonicsw.mf.mgmtapi.runtime ● Fault tolerance failover
Interface:
IAgentManagerProxy

Activation Daemon ● Activation daemon state

Package: ● Spawned container state and activation
com.sonicsw.mf.mgmtapi.runtime
Interface:
IActivationDaemonProxy

72 Progress SonicMQ Administrative Programming Guide V7.5

 Management Notifications

Component Notifications
Collections Monitor ● Collections Monitor state
Package: ● Monitored threshold exceeded
com.sonicsw.mf.mgmtapi.runtime
Interface:
ICollectionsMonitorProxy

Directory Service ● Directory Service state

Package: ● Changes to the Directory Service configuration
com.sonicsw.mf.mgmtapi.runtime ● Failover state of the Directory Service
Interface: ● Fault tolerance failover
IDirectoryServiceProxy

Broker ● Broker state

Package: ● Metric alerts
com.sonicsw.mq.mgmtapi.runtime ● Connection, flow control, and global subscription events
Interface: ● DMQ activity and state
IBrokerProxy ● Recovery log state

Notification Listeners and Persistent Notification Subscriptions

Containers write notification subscriptions to their cache directory. Persisted
subscriptions are removed from the cache when either:
● The JMX subscriber removes its subscription—in other words, when a JMX client
removes a notification listener or closes the connector.
● The subscription expires.
When a container restarts, it reads the JMX subscriptions persisted in its cache and
reestablishes those subscriptions with the Agent Manager. Subscriptions that are
recovered from the cache reset their expiration time to the point time when the recovery
occurred plus the original interval.

Progress SonicMQ Administrative Programming Guide V7.5 73

Chapter 3: Using the Runtime API for the Sonic Management Environment

Notification Subscription Methods for External JMX Clients

A managed container has notification subscription methods for external JMX clients:
● The existing method which defaults to an expiration duration of two times the default
renewal frequency (for a total of 60 seconds)
● A new method that adds a parameter for a specified interval before expiration is:
public void addNotificationListener(ObjectName objectName,
NotificationListener listener, NotificationFilter filter,
Object handback, Long timeout)
● A new method to add a notification listener with a specific notification subscription
expiration interval is:
public void addNotificationListener(ObjectName objectName,
NotificationListener listener, NotificationFilter filter,
Object handback, Long timeout)

JMX Connector Configuration and Behavior

The JMX connector client has methods for the Notification Subscription and Listener.
Methods to set/get a connector-wide notification subscription interval before expiration:
public void setNotificationSubscriptionTimeout(long timeout)
public long getNotificationSubscriptionTimeout ()
The following methods in com.sonicsw.mf.mgmtapi.runtime.IAgentManagerProxy provide
programmatic access to parameters that are useful in large scale deployments.

getAttributes
public AttributeList getAttributes(java.lang.String[] attributeNames)
Gets the values of several attributes of an AgentManager component. Getting multiple
attribute values at once is typically more efficient than getting individual attribute values.
Readable attributes (and their datatypes) exposed by an AgentManager that tune the
polling intervals and threads (useful features in large scale deployments) are:
● RefreshInterval (java.lang.Integer)
● CollectionInterval (java.lang.Integer)
● MinPollingThreads (java.lang.Integer)
● MaxPollingThreads (java.lang.Integer)

setRefreshInterval
public void setRefreshInterval(java.lang.Integer value)
Sets the value (in seconds) of the RefreshInterval attribute.

setCollectionInterval
public void setCollectionInterval(java.lang.Integer value)
Sets the value (in minutes) of the CollectionInterval attribute.
74 Progress SonicMQ Administrative Programming Guide V7.5
 Management Notifications

Filtering Notifications
Methods in the Management API let you create notification listeners and define the
filtration by notification types and attributes.

About Filters
Java Management Extensions (JMX) supports filtering of notifications such that a
management client can be configured to receive only a subset of the notifications
generated by a given source. JMX provides a simple notification type prefix filter.
SonicMQ additionally provides a more sophisticated filtering mechanism that allows
filtering by specifying regular expressions for the notification type and any number of the
attributes of the notification. Only notifications that match the specified regular
expressions are sent to the listening management application.
Within the selected notification types, the attributes of selected notifications can be
filtered based on an attribute value pattern also using regular expression syntax. When
only attribute expressions are specified in the filter and no notification types, all
notifications are evaluated against the attribute value patterns.

Filtering Notification Types

Methods in com.sonicsw.mf.jmx.client.ExptressionBasedNotificationFilter enable
regular expression rules to be defined for filtering on the notification type:

setTypeExpression
public void setTypeExpression(String expression)
Enable notifications of the type and the specified expression to be sent to the listener.
Setting the pattern to null clears a previously set expression.

getTypeExpression
public String getTypeExpression()
Gets the currently defined regular expression to be used for filtering by notification
type.

Progress SonicMQ Administrative Programming Guide V7.5 75

Chapter 3: Using the Runtime API for the Sonic Management Environment

Filtering Notification Attributes

Methods in com.sonicsw.mf.jmx.client.ExptressionBasedNotificationFilter enable
regular expression rules to be defined for filtering on the notification attribute values.

setAttributeExpression
public void setAttributeExpression(String attributeName, String expression);
Enables notifications with an attribute that matches the specified expression (and any
defined type expression or other attribute expressions) to be sent to the listener.
Setting the expression to null clears a previously set expression for the given attribute
name.

getAttributeExpressions
public Map getAttributeExpressions();
Gets previously set attribute expressions keyed by attribute.

clearAllAttributeExpressions
public void clearAllAttributeExpressions();
Clear all previously defined attribute name expressions.

Rules in Filters
The following rules apply to filters:
● Filters use regular expression syntax.
● Text is case sensitive.
● When no filter expression is defined, all notifications are filtered out.
● The structure of an expression string is Type Attribute Attribute ... which means that
if you intend to use a type filter, state it first, the add zero or more attribute filters to
further qualify the results of the previous part of the test.

76 Progress SonicMQ Administrative Programming Guide V7.5

 Management Notifications

Examples of Notification Filters

Setting up filters that use regular expression syntax might filter through notifications
where:
● The application session events is Subscribe or Unsubscribe
● And the TopicName is “App1Topic” or starts with “App2Topics.”
● And the UserName is “App1User” or “App2User”
The code segment that implements this filter is:
filter = new ExpressionBasedNotificationFilter();
filter.setTypeExpression("application\\.session\\.(S|Uns)ubscribe");
filter.setAttributeExpression("TopicName", "App1Topic|App2Topics\\..*");
filter.setAttributeExpression("UserName", "App[12]User");

Filtering for Only the Notification Type

In the previous example, if you skipped both setAttributeExpression lines:
filter = new ExpressionBasedNotificationFilter();
filter.setTypeExpression("application\\.session\\.(S|Uns)ubscribe");
the filter gets all the application session Subscribe or Unsubscribe event notifications.

Filtering Only the Attributes

In the previous example, if you skipped the setTypeExpression line:
filter = new ExpressionBasedNotificationFilter();
filter.setAttributeExpression("TopicName", "App1Topic|App2Topics\\..*");
filter.setAttributeExpression("UserName", "App[12]User");
the filter gets all the notification events where the TopicName is “App1Topic” or starts with
“App2Topics.” (which will be invalid for many types) and the UserName is “App1User” or
“App2User”.
Note This filter is used in the samples:
Management\runtimeAPI\jsProxy\FilteringNotificationReporter.js and
Management\runtimeAPI\javaProxy\FilteringNotificationReporter.java.

Progress SonicMQ Administrative Programming Guide V7.5 77

Chapter 3: Using the Runtime API for the Sonic Management Environment

Sonic Runtime API Samples

SonicMQ provides sample applications to help you get started with the Runtime API.
These samples are included in your SonicMQ installation, and located in the runtime
samples directory at: MQ7.5_install_root\samples\Management\runtimeAPI\.
The following subdirectories provide Java and JavaScript samples:
● javaJMX — A Java example showing how to monitor and operationally manage the
Sonic Management Environment using JMX (reflective) APIs
● javaProxy — A Java example showing how to monitor and operationally manage the
Sonic Management Environment using proxies that hide the underlying JMX APIs
and present an interface specific to the component being managed
● jsProxy — A JavaScript example showing how to monitor and operationally manage
the Sonic Management Environment using proxies that hide the underlying JMX
APIs and present an interface specific to the component being managed
These directories contain scripts that run the samples or configure the environment in
which to run the samples.
All samples directories have a readme.txt file that describes the contents more
completely. Where appropriate, the readme.txt file contains instructions for running more
complex samples.

JMX DynamicMBean Sample

The Java-based Command Line Interface (CLI) sample is located in the directory
MQ7.5_install_root\samples\Management\runtimeAPI\javaJMX. This sample demonstrates
how to use the JMX (reflective) DynamicMBean interface to write a generic management
application that has wide use across all types of manageable components that plug in to
the Sonic Management Environment.
This sample shows:
● The use of the JMS/JMX Connector Client and reporting of exceptions from that client
● Getting JMX MBean meta-data for MF compliant components (attributes, operations
and notifications)
● Getting and setting of management attributes
● Invoking management operations
● Subscribing to management notifications
● Accessing metrics exposed through the Sonic Management Environment

78 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

For more information about the features of this sample, see the comments in the file:
MQ7.5_install_root\samples\Management\runtimeAPI\javaJMX\MgmtCLI.java.

Important To execute the CLI sample you must already have installed the SonicMQ container.

◆ To run the CLI sample:

1. Start the default broker for the container.
2. Open a console window to the following directory:
MQ7.5_install_root\samples\Management\runtimeAPI\javaJMX

3. Enter the appropriate command for your platform:

■ For Windows, enter as a single line:
..\..\..\Mgmt MgmtCLI tcp://localhost:2506 Administrator Administrator
■ For UNIX, enter as a single line:
sh ../../../Mgmt.sh MgmtCLI tcp://localhost:2506 Administrator
Administrator

4. In the CLI shell you can get command help by typing a command followed by a
question mark (?) character. For example:
> subscribe ?

Most shell commands expect an argument specifying the JMX object name (or context)
to which the command should be applied. A default object name (or context) can be set
using the command cc, in which case the object name (or context) can be omitted from
the arguments.
The CLI commands that follow are supported by this sample.

capture
capture [<domain>.<container>:ID=<id>] <metric name>{,<metric name>...}

Captures and displays the values of given metric(s) in the given component context. If no
component context is provided, the current context is used. Multiple metric names must
be supplied as a comma separated list.

cc
cc <domain>.<container>:<id>

Change the current working context to the one provided.

Progress SonicMQ Administrative Programming Guide V7.5 79

Chapter 3: Using the Runtime API for the Sonic Management Environment

disable
disable [<domain>.<container>:ID=<id>] <metricName>{,<metricName>...}
Disables the given metric(s) in the given component context. If no component context is
provided, the current context is used. Multiple metric names must be supplied as a comma
separated list. Assumes the given metrics are dynamic, and therefore can be disabled.
For example, disable the thread count metric on the agent as follows:

> disable Domain1.Container1:ID=AGENT system.threads.CurrentTotal

enable
enable [<domain>.<container>:ID=<id>] <metricName>{,<metricName>...}
Enables the given metric(s) in the given component context. If no component context is
provided, the current context is used. Multiple metric names must be supplied as a comma
separated list. Assumes the given metrics are dynamic, and therefore can be enabled.
For example, you can enable the thread count metric on the agent, then capture that
metric, as shown:

> enable Domain1.Container1:ID=AGENT system.threads.CurrentTotal

> capture Domain1.Container1:ID=AGENT system.threads.CurrentTotal

(timestamp=Fri Jan 16 13:35:29 EST 2004)

- system.threads.CurrentTotal=90

exit
exit

Disconnects from the domain and exits this application.

get
get [<domain>.<container>:ID=<id>] <attributeName>{,<attributeName>,...}

Gets the current values of the requested attributes for the given component context. If no
component context is provided, the current context is used. Multiple attribute names must
be supplied as a comma separated list enclosed in quotes.
For example, to get the ConfigID attribute for the component
Domain1.Container1:ID=Broker1, enter the get command, as shown:

>get Domain1.Container1:ID=Broker1 ConfigID

ConfigID=/mq/brokers/0

80 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

invoke
invoke [<domain>.<container>:ID=<id>] <operationName> {param1,{param2...}}

Invokes an operation on the given component context. If no component context is

provided, the current context is used. Multiple parameters must be supplied as a comma
separated list (enclosed in quotes if spaces are required in individual parameter values).
Only operations that take base types as parameters are supported with this command.
Operations with multiple signatures are not fully supported (the first operation name
match that occurs will be used). Best attempts are made to display operation return values
(when available).
For example, invoke the operation saveLogFile( ) on the agent to save a log file to the
location c:/myLogFile.log, as shown:

> invoke Domain1.Container1:ID=AGENT saveLogFile c:/myLogFile.log

Open the log file to confirm it was created with the name and location you specified.

set
set [<domain>.<container>:ID=<id>] <attributeName> <attributeValue>

Resets the value of the given attribute of the given component context. If no component
context is provided, the current context is used.
For example, use get and set commands to retrieve and reset a component attribute value.
In this case, retrieve the metrics refresh interval for Broker1 and reset it to 30:

> get Domain1.Container1:ID=Broker1 MetricsRefreshInterval

MetricsRefreshInterval=20

> set Domain1.Container1:ID=Broker1 MetricsRefreshInterval 30

> get Domain1.Container1:ID=Broker1 MetricsRefreshInterval

MetricsRefreshInterval=30

Progress SonicMQ Administrative Programming Guide V7.5 81

Chapter 3: Using the Runtime API for the Sonic Management Environment

show
show {attributes|operations|notifications|metrics} [<domain>.<container>:<id>]

Shows the specified parameters exposed by the given components. If no component

context is provided, the current context is used.
show enabled [<domain>.<container>:<id>]

Shows the metrics currently enabled in the given component context. If no context is
provided, the current context is used.
show keywords

Shows all known command keywords.

show status [<domain>{<container>{:ID=<id>}}]

Shows the runtime state of the domain, container or component specified by the given
context. If no context is provided, the current context is used.

82 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

For example, to show the attributes of Domain1.Container1:ID=Broker1, enter the

command show attributes Domain1.Container1:ID=Broker1. A listing of attributes for
this component is returned, as shown in the following output:

> show attributes Domain1.Container1:ID=Broker1

ConfigID
- Configuration identity.
Classname
- Component classname.
ReleaseVersion
- Component release version.
State
- Execution state.
StateString
- Execution state description.
LastError
- Last (uncleared) error condition.
LastErrorLevel
- Last (uncleared) error severity.
LastErrorLevelString
- Last (uncleared) error severity description.
Uptime
- Execution time (milliseconds).
SharedNamespace
- Common component namespace.
Classpath
- Component classpath.
TraceMask
- Debug bit mask.
TraceMaskValues
- Possible TraceMask values.
MetricsRefreshInterval
- The number of seconds between refreshing of the statistical information on which metrics
are based.
MetricsCollectionInterval
- The number of minutes over which historical statistical information on which metrics are
based is collected.
BrokerName
- The configured broker name.
RoutingNodeName
- The configured routing node name.
ClusterName
- The name of the cluster to which the broker belongs (empty if the broker is not a member
of a cluster).
SecurityEnabled
- A flag indicating if the broker has security enabled.
ReplicationState
- 0=STARTUP,1=WAITING,2=STANDALONE,3=ACTIVE,4=STANDBY,5=ACTIVE_SYNC,6=STANDBY_SYNC
ReplicationStateString
- The current Replication State
ReplicationType
- PRIMARY or BACKUP

You can use the get command to get the value of any of these attributes (see “get” on
page 80).

Progress SonicMQ Administrative Programming Guide V7.5 83

Chapter 3: Using the Runtime API for the Sonic Management Environment

subscribe
subscribe
[<domain>.<container>:ID=<id>]<notificationType>{,<notificationType>...}

Subscribes to the given notification(s) on the given component context. If no component

context is provided, the current context is used. Multiple notification types must be
supplied as a comma separated list.
For example, subscribe to the notification system.state.Offline for the broker, the invoke
the reload( ) operation for the broker, and view the subscribed notifications, as shown:

> subscribe Domain1.Container1:ID=Broker1 system.state.Offline

> invoke Domain1.Container1:ID=Broker1 reload

[04/01/16 13:50:25] system.state.Offline (source=Domain1.Container1:ID=Broker1,

LastError=, LastErrorLevel=0)

unsubscribe
unsubscribe
[<domain>.<container>:ID=<id>]<notificationType>{,<notificationType>...}

Unsubscribes to the given notification(s) on the given component context. If no

component context is provided, the current context is used. Multiple notification types
must be supplied as a comma separated list.
For example, unsubscribe to the notification system.state.Offline for the broker, as
shown:

> unsubscribe Domain1.Container1:ID=Broker1 system.state.Offline

84 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

Java Proxy API Samples

SonicMQ provides Java Runtime API samples that use proxies in the directory
MQ7.5_install_root\samples\Management\runtimeAPI\javaProxy. This directory includes
the following Java samples:
● Shutdown.java — Shutdown a container
● ShowQueues.java — List broker queues
● ClearQueues.java — Clear queue messages
● NotificationReporter.java — Display broker notifications
● Common.java — Contains utility methods used by the samples in this directory
● BackupDS.java — Backup the Directory Service
● DBCompaction.java — Compacts a broker’s embedded data store.

The samples make use of proxies that mask the underlying JMX (reflective) calls. A
sample that directly uses the JMX API can be found in the directory:
samples\Management\runtimeAPI\javaJMX

Equivalent JavaScript-based samples can be found in the directory:

MQ7.5_install_root\samples\Management\runtimeAPI\jsProxy

Each sample is described in more detail in the following sections. When you run the
samples, each application interactively prompts for the specific information it requires.
Important To execute the javaProxy samples you must already have installed the SonicMQ
container.

◆ To run the Java proxy samples:

1. Start the default broker for the container.
2. Open a console window to the following directory:
MQ7.5_install_root\samples\Management\runtimeAPI\javaProxy

3. Enter the appropriate command for your platform:

■ For Windows, enter as a single line:
..\..\..\Mgmt <sample_classname>
■ For UNIX, enter as a single line:
sh ../../../Mgmt.sh <sample_classname>

Progress SonicMQ Administrative Programming Guide V7.5 85

Chapter 3: Using the Runtime API for the Sonic Management Environment

Shutdown.java
The Shutdown class and the static class it calls demonstrate using Java to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the agent component that
manages the container process)
● Execute an operation exposed through the Runtime API of the agent component (in
this case, an operation to shutdown the container)
After executing the program you should see the container shutdown. The shutdown can
be observed by looking at the stdout for the container process or viewing the runtime
status of the container in the Sonic Management Console.

ShowQueues.java
The ShowQueues class and the static class it calls demonstrate using Java to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the broker component)
● Execute an operation exposed through the Runtime API of the broker component (in
this case, an operation to get the queues managed by the broker)
After executing the program you should see the a list of queues and the number of
messages held on each queue managed by the broker. The results can be compared with
those shown in the Manage tab of the Sonic Management Console after selecting the
broker's Queues node.

ClearQueues.java
The ClearQueues class and the static class it calls demonstrate using Java to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the broker component)
● Execute an operation exposed through the Runtime API of the broker component (in
this case, an operation to clear messages from a particular set of queues managed by
the broker)
After executing the program you may want to execute the ShowQueues class in order to see
the effects of the ClearQueues class.

86 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

NotificationReporter.java
The NotificationReporter class and the static class it calls demonstrate using java to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the broker component)
● Create a notification listener that will display management notifications emitted by
the broker
This program will continue to listen and display received notifications until it is
terminated. Use Ctrl-C to terminate the program. For each notification received, the
notification name (or type) and the source of the notification will be displayed.
Notifications, such as those generated when clients connect and disconnect, can be
created using the JMS Test Client application or running one of the programs described
in this section (for example, ShowQueues) from another shell.

FilteringNotificationReporter.java
The FilteringNotificationReporter class and the static class it calls demonstrate using
Java to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the broker component)
● Create a notification listener and regular expression based notification filter that will
display a filtered set of management notifications (based on both the notification type
and attribute values) emitted by the broker
This program will continue to listen and display received notifications until it is
terminated. Use Ctrl-C to terminate the program. For each notification received, the
notification name (or type) and the source of the notification is displayed.
The code segment that does the filtering in this example is:

// create a Sonic expression based filter and setup some filtering rules
ExpressionBasedNotificationFilter filter = new ExpressionBasedNotificationFilter();

// set a rule so that we receive only notifications of type "application.session.Subscribe"

// and "application.session.Unsubscribe", and for the topics "App1Topic" and "App2Topics.*"
// and a user name of "App1User" or "App2User"
filter.setTypeExpression("application\\.session\\.(S|Uns)ubscribe");
filter.setAttributeExpression("TopicName", "App1Topic|App2Topics\\..*");
filter.setAttributeExpression("UserName", "App[12]User");

Notifications generated when clients subscribe and unsubscribe can be created by using
the JMS Test Client application and TopicPubSub samples such as Chat.

Progress SonicMQ Administrative Programming Guide V7.5 87

Chapter 3: Using the Runtime API for the Sonic Management Environment

BackupDS.java
The BackupDS class and the static class it calls demonstrate one way to perform a backup
of the Directory Service storage, using Java to:
● Create a JMS JMX Connector Client.
● Create a runtime proxy for a component (in this case the Directory Service
component that manages the domain's configuration store).
● Set an attribute exposed through the Runtime API of the Directory Service
component in order to place the Directory Service in a state under which it is valid to
take an online backup of the domain's configuration store.
● Prompt the user to perform the backup (tar, copy, etc.) and indicate when the backup
is complete.
● Reset the online backup attribute in order to place the Directory Service back to a state
where it can handle further configuration updates.
As the Directory Service is placed in and out of the online backup mode, you can observe
related messages on the Directory Service’s container standard output.
As an additional exercise, you can try executing your backup process directly from the
program, replacing the standard input prompting.

DBCompaction.java
The DBCompaction class shows how to invoke a database compaction reques remotely, and
check on its status, using Java to:
● Set the administrative connection information, broker identity, and working directory.
● Enable a forceStop that forces the db compaction operation to stop after the specified
time interval.
The broker whose data storage you want to compact must be in a stopped state yet the
management container that hosts that broker must be running. To do this, you must do one
of the following:
● Start the management container that hosts the broker. Then, on the Manage tab in the
SMC, right-click on the broker, and choose Operations > Stop.
● On the SMC Configure tab, right-click on the hosted broker component in the
management container, choose Properties, and then clear the Auto Start option. Then
start the management container. (Select the option again after you complete the
compaction task.)
The application initiates the operation and does not report on its results.

88 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

Until the compaction action has completed:

● Do not reload or stop the management container.
● Do not reload or start the broker.
● Do not attempt other storage operatons.

JavaScript Proxy API Samples

SonicMQ provides JavaScript Runtime API samples in the directory
MQ7.5_install_root\samples\Management\runtimeAPI\javaProxy. This directory includes
the following sample scripts:
● Shutdown.js — Shutdown a container
● ShowQueues.js — List broker queues
● ClearQueues.js — Clear queue messages
● NotificationReporter.js — Display broker notifications
● Common.js — Contains utility functions used by the samples in this directory
● BackupDS.js — Backup the Directory Service storage

Equivalent Java-based samples can be found in the directory:

MQ7.5_install_root\samples\Management\runtimeAPI\javaProxy

Each sample script is described in more detail in the following sections. Each script
assumes the installation default values were selected for domain name, container name,
broker port, etc. If you made non-default selections during installation, you must modify
the scripts appropriately.
Important To execute the jsProxy samples you must already have installed the SonicMQ container.

◆ To run the JavaScript proxy samples:

1. Start the default broker for the container.
2. Open a console window to the following directory:
MQ7.5_install_root\samples\Management\runtimeAPI\jsProxy

3. Enter the appropriate command for your platform:

■ For Windows, enter as a single line:
..\..\..\jsRun <scriptfile>
■ For UNIX, enter as a single line:
sh ../../../jsRun.sh <scriptfile>

Progress SonicMQ Administrative Programming Guide V7.5 89

Chapter 3: Using the Runtime API for the Sonic Management Environment

Shutdown.js
The Shutdown.js script and the script functions it calls demonstrate using JavaScript to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case the agent component that
manages the container process)
● Execute an operation exposed through the Runtime API of the agent component (in
this case an operation to shutdown the container)
After executing this script you should see the container shutdown. The shutdown can be
observed by looking at the stdout for the container process or viewing the runtime status
of the container in the Sonic Management Console.

ShowQueues.js
The ShowQueues.js script and the script functions it calls demonstrate using JavaScript to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the broker component)
● Execute an operation exposed through the Runtime API of the broker component (in
this case, an operation to get the queues managed by the broker)
After executing this script you should see the a list of queues and the number of messages
held on each queue managed by the broker. The results can be compared with those shown
in the Manage tab of the Sonic Management Console after selecting the broker's Queues
node.

ClearQueues.js
The ClearQueues.js script and the script functions it calls demonstrate using JavaScript
to:
● Create a JMS JMX Connector Client
● Create a runtime proxy for a component (in this case, the broker component)
● Execute an operation exposed through the Runtime API of the broker component (in
this case, an operation to clear messages from a particular set of queues managed by
the broker)
After executing this script you can execute the ShowQueues.js script to see the effects of
the ClearQueues.js script.

90 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic Runtime API Samples

NotificationReporter.js
The NotificationReporter.js script and the script functions it calls demonstrate using
JavaScript to:
● Create a JMS JMX Connector Client.
● Create a runtime proxy for a component (in this case, the broker component).
● Create a notification listener that will display management notifications emitted by
the broker.
This script will continue to listen and display received notifications until it is terminated.
Use Ctrl-c to terminate the program.
For each notification received, the notification name (or type) and the source of the
notification will be displayed.
Notifications, such as those generated when clients connect and disconnect, can be
created using the JMS Test Client application or running one of the scripts described in
this section (for example, ShowQueues.js) from another shell.

FilteringNotificationReporter.js
The FilteringNotificationReporter.js script and the script functions it calls
demonstrate using JavaScript to:
● Create a JMS JMX Connector Client.
● Create a runtime proxy for a component (in this case, the broker component).
● Create a notification listener and Sonic regular expression based notification filter that
will display a filtered set of management notifications (based on both the notification
type and attribute values) emitted by the broker.
This script will continue to listen and display received notifications until it is terminated.
Use Ctrl-C to terminate the program.
For each notification received, the notification name (or type) and the source of the
notification is displayed.

Progress SonicMQ Administrative Programming Guide V7.5 91

Chapter 3: Using the Runtime API for the Sonic Management Environment

The code segment that does the filtering in this example is:

// create a Sonic expression based filter and setup some filtering rules
ExpressionBasedNotificationFilter filter = new ExpressionBasedNotificationFilter();

// set a rule so that we receive only notifications of type "application.session.Subscribe"

// and "application.session.Unsubscribe", and for the topics "App1Topic" and "App2Topics.*"
// and a user name of "App1User" or "App2User"
filter.setTypeExpression("application\\.session\\.(S|Uns)ubscribe");
filter.setAttributeExpression("TopicName", "App1Topic|App2Topics\\..*");
filter.setAttributeExpression("UserName", "App[12]User");

Notifications generated when clients subscribe and unsubscribe can be created by using
the JMS Test Client application and TopicPubSub samples such as Chat.

BackupDS.js
The BackupDS script and the script functions it calls demonstrate one way to perform a
backup of the Directory Service storage, using JavaScript to:
● Create a JMS JMX Connector Client.
● Create a runtime proxy for a component (in this case the Directory Service
component that manages the domain's configuration store).
● Set an attribute exposed through the Runtime API of the Directory Service
component in order to place the Directory Service in a state under which it is valid to
take an online backup of the domain's configuration store.
● Prompt the user to perform the backup (tar, copy, etc.) and indicate when the backup
is complete.
● Reset the online backup attribute in order to place the Directory Service back to a state
where it can handle further configuration updates.
As the Directory Service is placed in and out of the online backup mode, you can observe
related messages on the Directory Service’s container standard output.
As an additional exercise, you can try executing your backup process directly from the
program, replacing the standard input prompting.

92 Progress SonicMQ Administrative Programming Guide V7.5

Chapter 4 Using the Directory Service API for Sonic
Management Security

Chapter 4 describes using the SonicMQ Directory Service API, which provides
programmatic access to the Directory Service to maintain permissions enforcement and
auditing:
● “Overview of the Directory Service (DS) API”
● “Interfaces”
● “Factory Operations”
● “Sonic DS API Sample”

Progress SonicMQ Administrative Programming Guide V7.5 93

Chapter 4: Using the Directory Service API for Sonic Management Security

Overview of the Directory Service (DS) API

The Directory Service API enables programmatic maintenance of management security
features. The Directory Service API is documented as part of the Management
Application API Reference, accessible from the SonicMQ documentation page. That
Javadoc is installed at sonic_install_dir/Docs7.5/api/mgmt/api/index.html.
The process of configuring permissions enforcement requires the following additional
steps in maintenance of brokers, groups, ACLS, and users (and programmatically through
the appropriate API):
1. Set the SET_JMXSXUSERID advanced broker property on the management brokers
(Config API).
2. Reload the management brokers (Runtime API).
3. Enable permissions enforcement in the domain (DS API).
4. Create groups in the authentication domain (Config API).
5. Create ACLs in the authorization policy (Config API).
6. Define permissions (DS API).
7. Add users to groups (Config API).
See Chapter 15, “Management Security,” in the Progress SonicMQ Deployment Guide for
a detailed example of these steps.

Interfaces
The IManagementSecurityConfigurator interface provides the methods used by
administration clients to enable and configure the management security features:
● Configuration and runtime checking of management permissions
● Auditing of configuration and/or runtime events.
Creation and use of an instance of this interface is demonstrated in the installed sample
sonic_install_root/MQ7.5/samples/Management/mgmtSecurityAPI/java.

The paths parameter is the organizational hierarchy shown in the Configured Objects
section of the Configure tab in the Sonic Management Console.

94 Progress SonicMQ Administrative Programming Guide V7.5

 Factory Operations

The hierarchy extends to the following types of nodes:

● Folders (including the root folder)
● Component configurations (such as brokers, activation daemons, and agent
managers)
● Non-component configurations (such as authentication domains, and collections)
● Files (such as, JARs and CARs that are accessible through the sonicfs:/// protocol)
The paths parameter of a folder is specified as:
logical_path
For example: /East/Southeast
The paths parameter of a component in a container is specified as:
logical_path_to_container:ID=component_name
For example: /East/SouthEast/SEContainer1:ID=SEBroker1

Factory Operations
The ManagementPermissionsFactory lets you create instances of IManagementPermission.

Principal
A principal is a group or user name in the Authentication Domain assigned for
permissions enforcement.
● setPrincipal(String principal)
● String getPrincipal()

Scope
Scope setting methods in the DS API are:
● setScope(int scope)
● int getScope()

A scope is defined as a bit mask whose values are formed by adding constants. The scope
constants, located in sonic_install_dir/Docs7.5/api/mgmt_api/constant-values.html,
are:
com.sonicsw.mf.common.security.IConfigureScopeBits
public static final int THIS_FOLDER_SCOPE1
public static final int ALL_FOLDERS_SCOPE 2
public static final int THIS_CONFIGURATION_OR_FILE_SCOPE 4
public static final int ALL_CONFIGURATIONS_AND_FILES_SCOPE 8

Progress SonicMQ Administrative Programming Guide V7.5 95

Chapter 4: Using the Directory Service API for Sonic Management Security

com.sonicsw.mf.common.security.IManageScopeBits
public static final int ALL_FOLDERS_SCOPE 1
public static final int THIS_CONTAINER_SCOPE 2
public static final int ALL_CONTAINERS_SCOPE 4
public static final int THIS_COMPONENT_SCOPE 8
public static final int ALL_COMPONENTS_SCOPE 16

Permissions
Permission setting methods in the DS API are:
● setPermissions(int permissions)
● int getPermissions()

A permission setting is a bit mask whose values are formed by adding constants.
Both allow and deny constants are available for each permission. Avoid invalid
combinations, such as ALLOW_READ + DENY_READ, in which case the allow permission is
recorded (hence, ALLOW_READ + DENY_READ = ALLOW_READ.) Other invalid combinations are
functional mismatches such as ALLOW_DELETE+DENY_WRITE.
Permission constants, located in sonic_install_dir/Docs7.5/api/mgmt_api/constant-
values.html, are:
com.sonicsw.mf.common.security.IConfigurePermissionBits
public static final int ALLOW_READ 1
public static final int DENY_READ2
public static final int ALLOW_WRITE 4
public static final int DENY_WRITE 8
public static final int ALLOW_DELETE 16
public static final int DENY_DELETE32
public static final int ALLOW_SET_PERMISSIONS 64
public static final int DENY_SET_PERMISSIONS 128

com.sonicsw.mf.common.security.IManagePermissionBits
public static final int ALLOW_LIFE_CYCLE_CONTROL 1
public static final int DENY_LIFE_CYCLE_CONTROL 2
public static final int ALLOW_ENABLE_DISABLE_METRICS 4
public static final int DENY_ENABLE_DISABLE_METRICS 8
public static final int ALLOW_NOTIFICATION_SUBSCRIPTION16
public static final int DENY_NOTIFICATION_SUBSCRIPTION 32
public static final int ALLOW_SET_ATTRIBUTES64
public static final int DENY_SET_ATTRIBUTES 128
public static final int ALLOW_PERFORM_ACTIONS 256
public static final int DENY_PERFORM_ACTIONS 512
public static final int ALLOW_GET_INFORMATION 1024
public static final int DENY_GET_INFORMATION 2048

96 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic DS API Sample

When a value is neither set to allow or to deny an action, the permission is not considered
to be defined in the setting. For example, if you set a principal’s permissions to
ALLOW_READ+ALLOW_WRITE and the action is delete, then the permission resolution will
search for another setting.

Sonic DS API Sample

The sample provided for the Sonic Directory Service API is located in an installation at:
sonic_install_dir/MQ7.5/samples/Management/mgmtSecurityAPI/java

The sample is a Java-based Command Line Interface (CLI) for the enablement of
permissions enforcement and auditing using the DS API. You can display and maintain
the domain-wide management security settings, as well as add, list, update, and delete
configure permissions and manage permissions.
After you explore the behavior of the commands in this shell, deconstruct its source file,
MgmtSecurityCLI.java, to review the coding details.

◆ To run the DS API (Management Security CLI) sample:

1. Start the default broker for the SonicMQ container:
Start > Programs > Progress Sonic > SonicMQ 7.5 > SonicMQ DomainManager
2. Open a console window to the following directory:
MQ7.5_install_root\samples\Management\SecurityAPI\java

3. Enter the appropriate command for your platform:

■ For Windows, enter:
..\..\..\Mgmt MgmtSecurityCLI domain host:port user password
Using a default installation’s parameters, the command is:
..\..\..\Mgmt MgmtSecurityCLI Domain1 localhost:2506 Administrator Administrator
■ For UNIX/Linux, enter:
sh ../../../Mgmt.sh MgmtSecurityCLI domain host:port user password

The Sonic DS API CLI connects to the domain.

You can get online help by typing a command followed by a ? For example, if you enter:
> show ?

and press Enter, the response lists the keywords tat can follow show:
Commands are: audit configure enforcement help keywords manage

Progress SonicMQ Administrative Programming Guide V7.5 97

Chapter 4: Using the Directory Service API for Sonic Management Security

Commands that Control Management Security and Auditing

The general settings that enable and disable permissions enforcement and auditing can be
changed by the Administrator user only. These commands should be used carefully.

Management Security
> enable enforcement authentication_domain_path
> enable default permissions
> show enforcement
> disable all permissions
> disable enforcement

Auditing
> enable configure audit
> enable manage audit
> enable central audit
> set audit config URL
> show audit
> disable configure audit
> disable manage audit
> disable central audit

Commands that Set Context

> {changeContext | cc} paths
The enable, disable, and show permission commands require that you first set the context
of the namespace where you want to apply the command. Unlike a cd command, you must
enter the entire path in one command. For example, assume the domain has a folder
structure, as shown:

To set the context to the /East/SouthEast folder, enter:

> cc /East/Southeast
not
> cc /East
East> cc /Southeast
The current path is shown in the prompt on the command line, as shown:
/East/SouthEast>

98 Progress SonicMQ Administrative Programming Guide V7.5

 Sonic DS API Sample

Commands that Set Configure Permissions

The following commands set configure permissions for the current context:
> enable configure permission principal scope permission
> show configure permissions
> show configure scope bits
> show configure permission bits
> disable configure permission principal

Commands that Set Manage Permissions

The following commands set manage permissions for the current context:
> enable manage permission principal scope permission
> show manage permissions
> show manage scope bits
> show manage permission bits
> disable manage permission principal

Progress SonicMQ Administrative Programming Guide V7.5 99

Chapter 4: Using the Directory Service API for Sonic Management Security

100 Progress SonicMQ Administrative Programming Guide V7.5

Chapter 5 Using the Advanced Security SPIs for the
Sonic Authentication Domains

Chapter 5 describes using the SonicMQ Server Provider Interfaces (SPIs) for
implementing the Pluggable Authentication and Security Service (PASS). This chapter
contains the following sections:
● “Overview of the PASS SPIs” — Introduces the PASS SPIs, which include the Login,
Authentication, and Management SPIs
● “Login SPI” — Describes the Login SPI interfaces, with which you can implement
your own custom login modules or plug in JAAS-based authentication functionality
● “Authentication SPI” — Describes the Authentication SPI, which you configure for
a broker having an external Authentication Domain
● “Management SPI” — Describes the Management SPI, which you can implement to
retrieve users and groups from any third-party security store

Progress SonicMQ Administrative Programming Guide V7.5 101

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

Overview of the PASS SPIs

Three SPIs provide access to the Pluggable Authentication and Security Service (PASS)
functionality in SonicMQ. Implement the following SPIs to use the advanced security
features in the SonicMQ product:
● Login SPI — The package com.sonicsw.security.pass.client provides access to the
ILogin and IPasswordUser interfaces, which are used to authenticate JMS client
applications with external security domains residing on the client side.
● Authentication SPI — The package com.sonicsw.security.pass.broker provides
access to the IAuthentication and IBrokerSecurityCache interfaces. IAuthentication
is used to authenticate JMS clients connecting to a broker via the delegation mode,
and IBrokerSecurityCache is used to perform callback operations on the broker.
Implementation of these interfaces requires implementing the Login SPI on the client
side.
● Management SPI — The package com.sonicsw.security.pass.mf provides access to
the IEvent, IGroup, IManagement, and INotificationListener interfaces, which are
used by the Sonic Directory Service to replicate users and credentials into the Sonic
Directory Service. This information is used by the Sonic Management Console
(SMC), which provides a graphical read-only representation of users and groups in
the external domain.
You can implement an external security store for an authentication domain, in addition to
the local security store that is implemented by default for all authentication domains:
● Local security store — Users are stored in the Sonic Directory Service.
● External security store — Users are stored externally and accessed by the
Authentication SPI and the Management SPI.
A password stored in an external security store is stored in an unknown format. You
must implement the Login SPI to perform password transformations when using an
external security store.
SonicMQ includes sample code you can examine to understand how to implement these
security features in your applications. This chapter includes some code excerpts from
these samples to illustrate how to implement the PASS SPIs.
See the file MQ7.5_install_root\samples\AdvancedSecurity\readme.htm for information
about samples that demonstrate advanced security features using the PASS SPIs.
For information about running the security sample, and for more information about the
PASS features in SonicMQ, see the chapter “Security Considerations in System Design”
in the Progress SonicMQ Deployment Guide.

102 Progress SonicMQ Administrative Programming Guide V7.5

 Login SPI

See the chapter “Configuring Security” in the Progress SonicMQ Configuration and
Management Guide for information about using the SMC to configure these security
features in SonicMQ.

Login SPI
The Login SPI provides access to the ILogin and IPasswordUser interfaces. You can
implement these interfaces in order to use your own custom login modules. You can also
use the login module to plug in JAAS-based authentication functionality. When you
implement the Login SPI, users can be authenticated with external authentication service
before a JMS connection is created, either by a proprietary or JAAS login module
implementation. The Login SPI includes the following interfaces:
● ILogin — Provides methods to authenticate JMS client applications with one or many
external security domains
● IPasswordUser — Provides methods to get a user’s credentials for authentication

Both these interfaces are located in the package: com.sonicsw.security.pass.client.

Login and PasswordUser SPI Implementation in the SonicMQ

Runtime
The Login SPI is used internally by the SonicMQ JMS client runtime. When a JMS
connection is requested from a connection factory, the following sequence of events
occurs:
1. The Login SPI class is loaded into the application’s JVM and a new instance of the
class is created.
2. The SonicMQ runtime calls the method getLoginSPI( ), which returns an ILogin
instance to be used for further authentication processing.
3. Upon successful instantiation of the class, the SonicMQ runtime passes the user name
and the password to the underlying SPI implementation using the methods:
■ setUserName(String username)
■ setPassword(String password)

4. The SonicMQ runtime calls the method login( ) on the underlying SPI
implementation.

Progress SonicMQ Administrative Programming Guide V7.5 103

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

5. If the login( ) method returns without an exception, the login to external security
store or schema is assumed validated and user is considered authenticated.
6. Upon successful return from the login( ) method, the SonicMQ runtime calls the
getCredential( ) method to retrieve the user name and the transformed password via
an implementation of IPasswordUser.
7. The retrieved user name, password, and transformed password are used to establish a
JMS connection.
The transformed password is used when the SonicMQ broker is configured with an
external Authentication Domain. This is a delegation mode of the authentication process
in which the transformed password is transmitted across the wire to the SonicMQ broker.
The broker authenticates the connecting client using the transformed password via a
configured Authentication SPI.
For example, assume a user testUser has a password testPassword. The application
implements the Login SPI, and the getCredential( ) method returns an instance of
IPasswordUser with user name testUser and a byte[ ]password.

The client is unaware that the broker is configured with an external Authentication
Domain. While a connection is being established, one of the following two things can
happen, depending on whether the user is found in the security cache:
● The broker finds that there is an internal user testUser — The broker then uses the
password testPassword to authenticate the user (this is the regular challenge and
response).
● The user testUser is not present in the broker’s security cache — The user is then
considered an external user and the broker requests the byte[ ] password from the
client application. When the broker gets the byte[ ] password from the client, the
broker calls Authentication SPI's authenticate method.
The following code example shows how to create a topic connection to the SonicMQ
broker, invoking the Login SPI implementation. This code example assumes a user
testUser with the password testPassword exists as a valid Sonic user. This code example
is excerpted from the file JMSClient.java, located at:
MQ7.5_install_root\samples\AdvancedSecurity\com\sonicsw\samples\pass\
extAuthDomain\loginspi\

104 Progress SonicMQ Administrative Programming Guide V7.5

 Login SPI

The full code sample includes an example of how to create a queue connection and
message listeners, and how to handle messages received:

...
// Create a connection.
try
{
System.out.println("\r\nTesting creation of a TopicConnection");
javax.jms.TopicConnectionFactory factory;

factory = (new progress.message.jclient.TopicConnectionFactory(m_brokerName));

((progress.message.jclient.ConnectionFactory)factory).setLoginSPI(m_loginSPIClassName);
m_topicConnection = factory.createTopicConnection(m_username, m_password);
System.out.println("created a TopicConnection");
}

The following code example shows how to implement the IPasswordUser interface:

package com.sonicsw.samples.pass.extAuthDomain.loginspi;

import com.sonicsw.security.pass.client.IPasswordUser;

public final class PasswordUser implements IPasswordUser

{
//user name
String m_userName;

//user password
String m_password;

//external groups the user belongs to in the external security store

String[] m_groups;

//Default Constructor
private PasswordUser()
{
}
/**
* Constructor
* <p>
* @param uid user name
* @param pwd user's password
*/
public PasswordUser(String uid, String pwd)
{
m_userName = uid;
m_password = pwd;
}

Progress SonicMQ Administrative Programming Guide V7.5 105

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

//see com.sonicsw.security.pass.client.IPasswordUser#getPassword()
//see com.sonicsw.security.pass.broker.IAuthentication#authenticate(java.lang.String,
//byte[])

public byte[] getPassword()

{
// Here, plug-in your password transformation logic. After transformation
// you can even encrypt the bytes and decrypt it at the implementation of
// Authentication SPI's authenticate method.
if (m_password != null)
return m_password.getBytes();
else
return null;
}
//see com.sonicsw.security.pass.client.IPasswordUser#getGroups()

public String[] getGroups()

{
return m_groups;
}

//see com.sonicsw.security.pass.client.IPasswordUser#setGroups(java.lang.String[])

public void setGroups(String[] groups)

{
m_groups = groups;
}

//see java.security.Principal#getName()

public String getName()

{
return m_userName;
}
}

That example was excerpted from the file PasswordUser.java, located at:
MQ7.5_install_root\samples\AdvancedSecurity\com\sonicsw\samples\pass\
extAuthDomain\loginspi.

106 Progress SonicMQ Administrative Programming Guide V7.5

 Login SPI

The following code example shows how to test a Login SPI implementation when
connecting to the SonicMQ broker by testing the authentication of a flat file user.

package com.sonicsw.samples.pass.extAuthDomain.loginspi;

import com.sonicsw.security.pass.client.ILogin;
import com.sonicsw.security.pass.client.IPasswordUser;

public final class LoginSpiImpl implements ILogin

{
//preserving the instance of ILogin
private static ILogin m_login;
private String m_username;
private String m_password;

//Default Constructor
public LoginSpiImpl()
{
m_login = this;
}
//see com.sonicsw.security.pass.client.ILogin#getCredential()
public IPasswordUser getCredential()
{
return new PasswordUser(m_username, m_password);
}
//see com.sonicsw.security.pass.client.ILogin#getLoginSPI()
public ILogin getLoginSPI()
{
return m_login;
}
//see com.sonicsw.security.pass.client.ILogin#setPassword(java.lang.String)
public void setPassword(String password)
{
m_password = password;
}
//see com.sonicsw.security.pass.client.ILogin#setUserName(java.lang.String)
public void setUserName(String username)
{
m_username = username;
}
//see com.sonicsw.security.pass.client.ILogin#login()
public boolean login()
{
// TODO
// Here, you can write your own login function/call.
// If error, return false. Else return true.
return true;
}
//see com.sonicsw.security.pass.client.ILogin#logout()
public void logout()
{
// Do nothing
}
}

That example was excerpted from LoginSpiImpl.java, located at: MQ7.5_install_root

\samples\AdvancedSecurity\com\sonicsw\samples\pass\extAuthDomain\loginspi

Progress SonicMQ Administrative Programming Guide V7.5 107

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

Login SPI and JAAS authentication

You can use JAAS to write your own authentication and authorization applications. You
can do this before creating a JMS connection through the SonicMQ JMS client. When a
user is authenticated and/or authorized, that user can create a JMS connection.
When you implement the ILogin interface provided by SonicMQ in your authentication
and/or authorization application, the SonicMQ client runtime will use it as described in
“Login and PasswordUser SPI Implementation in the SonicMQ Runtime” on page 103.
Writing and using a JAAS-based Login SPI requires the following:
1. An authentication application that implements the Login SPI.
2. Optional — Implementation of javax.security.auth.callback.CallbackHandler to
be used by the authentication application.
3. Implementation of javax.security.auth.spi.LoginModule.
4. Implementation of java.security.Principal interface to be used by
javax.security.auth.spi.LoginModule.

5. Appropriate configuration (for example, AnySimpleJAAS.config) file used by the

JVM.

Configuring the Login SPI

The Login SPI can be plugged into the Sonic JMS client through the ConnectionFactory.
The following example shows how to plug in and use a Login SPI implementation to a
JMS client. Assume that sonic.pass.loginspi.impl.BasicLogin is a class implementing
the interface com.sonicsw.security.pass.client.ILogin.
If the factory is a TopicConnectionFactory, the Login SPI can be configured as:

String m_loginSPIClassName = "sonic.pass.loginspi.impl.BasicLogin";

((progress.message.jclient.ConnectionFactory)factory).setLoginSPI(m_loginSPIClassName);

Alternatively, you can configure the Login SPI implementation using the following JVM
argument:
-DSonicMQ.LOGIN_SPI=sonic.pass.loginspi.impl.BasicLogin

Note A Login SPI configured using the ConnectionFactory takes precedence over a Login API
configured using a JVM argument.

108 Progress SonicMQ Administrative Programming Guide V7.5

 Authentication SPI

The package com.sonicsw.samples.pass.loginSPI.simple contains sample files that

demonstrate how to configure a Login SPI on the SonicMQ client side. These files
include:
● Chat.java — A sample JMS client
● SimpleLoginSPI.java — An implementation of interface
com.sonicsw.security.pass.client.ILogin.
● SimplePasswordUser.java — An implementation of the interface
com.sonicsw.security.pass.client.IPasswordUser

See the file MQ7.5_install_root\samples\AdvancedSecurity\readme.htm for information

about running a sample application that uses these implementations.

Authentication SPI
The Authentication SPI provides access to the following interfaces:
● IAuthentication — Provides the methods required for delegation mode authentication
of JMS clients connecting to the broker.
● IBrokerSecurityCache — Provides callback operations required to find external users
cached on the broker.
Both these interfaces are located in the package: com.sonicsw.security.pass.broker.

Authentication SPI Implementation in the SonicMQ Runtime

The broker is configured with an external Authentication Domain using an Authentication
SPI. The Authentication SPI configuration contains the Authentication SPI name,
classname, and classpath. The authentication domain configuration uses this
preconfigured Authentication SPI. Users can add attributes as name-value pairs when
configuring the authentication domain. These attributes are passed to the Authentication
SPI implementation as a HashMap.
Code examples used to illustrate the following steps are excerpted from the file
Authentication.java, located at:
MQ7.5_install_root\samples\AdvancedSecurity\com\sonicsw\samples\pass
\extAuthDomain\authspi

Progress SonicMQ Administrative Programming Guide V7.5 109

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

When the broker starts, the following sequence of events occurs:

1. The broker instantiates the Authentication SPI and passes the attributes by calling the
setConfigInfo(HashMap) method. For example:

...
// create an instance of this class
Authentication sample = new Authentication();

// Load the properties file

...

// SonicMQ runtime now sets the Attribute Settings in the Authentication

// SPI implementation
sample.m_configuration = new HashMap();

if (prop != null && prop.size() > 0)

sample.m_configuration.putAll(prop);
String s = (String)sample.m_configuration.get(AUTHENTICATION_TRACE);

if (s != null && s.equalsIgnoreCase("true"))

s_verbose = true;

if (s_verbose)
System.out.println("\r\n----- Authentication.main() -------");

// SonicMQ runtime calls setConfigInfo

// The configuration is received by the Broker and passed to the
// Authentication SPI implementation.
sample.setConfigInfo(sample.m_configuration);

2. The broker calls init( ) on the implementation. For example:

// SonicMQ runtime calls init

try
{
sample.init();
}
catch (ConnectionException ex)
{
ex.printStackTrace();
System.exit(0);
}

110 Progress SonicMQ Administrative Programming Guide V7.5

 Authentication SPI

3. The broker calls setSecurityCache(IBrokerSecurityCache) to set the broker cache

instance to the SPI implementation for callback operations. For example:

//Set the security cache

//see com.sonicsw.security.pass.broker.IAuthentication
//#setSecurityCache(com.sonicsw.security.pass.broker
//.IBrokerSecurityCache)
public void setSecurityCache(IBrokerSecurityCache cache)
{
m_cache = cache;
}

4. The broker updates the credential of the external user cached on the broker, if any. For
example:

//The Broker, based on internal rules/conditions, will use this

// method to update credential of external users.
//see com.sonicsw.security.pass.broker.IAuthentication
//#updateUserInfo(java.lang.String[])

public IPasswordUser[] updateUserInfo(String[] users) throws

ConnectionException {

if (users == null)
return null;
try
{
ArrayList list = new ArrayList();

for (int i = 0; i < users.length; i++)

{
String uid = users[i];
if (uid != null)
{
IPasswordUser u = (IPasswordUser)m_passwordUser.get(uid);
if (u != null)
list.add(u);
}
}
if (list != null && !list.isEmpty())
{
IPasswordUser[] pUsers = new IPasswordUser[list.size()];
list.toArray(pUsers);
return pUsers;
}
}
catch (Exception e)
{
e.printStackTrace();
}
return null;
}

Now the Authentication SPI in the external Authentication Domain is ready for use.

Progress SonicMQ Administrative Programming Guide V7.5 111

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

As a user tries to establish a JMS connection with a secured broker, the broker checks for
the user's credential in the broker cache. One of the following two things can happen,
depending on whether the user is found in the internal cache:
● The user is an internal user — Regular Challenge and Response based authentication
is used.
● The user is not found in the internal user cache (and an Authentication SPI has been
configured on the broker) — The broker sends a request to the client JMS application
to send the credentials. The SonicMQ client runtime uses the Login SPI to provide
the byte[ ] of the credential. This byte[ ] is transmitted to the broker.
The broker then passes the user name with the byte[ ] to the Authentication SPI
implementation. If the SPI throws an exception, the user is considered
unauthenticated.
Upon successful authentication, the Authentication SPI returns a group array of groups to
which the user belongs. These groups are defined in the external store—they are not
SonicMQ groups. These external groups are mapped to internal groups in the Group Map
for the external Authentication Domain. (See the chapter “Configuring Security” in the
Progress SonicMQ Configuration and Management Guide for information about using
the Sonic Management Console (SMC) to configure a Group Map for an external
Authentication Domain.)
For example, a user Bob might belong to three groups: Employee, HR Manager, and
Directory Administrator. In this case, the String[ ] returned contains Employee, HR
Manager, and Directory Administrator as three items in the array.

These returned groups are used to add the user to the appropriate ACL entry. By default,
the user is also added to the internal PUBLIC group, as user must belong to this internal
group to perform JMS messaging.

112 Progress SonicMQ Administrative Programming Guide V7.5

 Authentication SPI

Configuring the Authentication SPI for an External

Authentication Domain
To use the Authentication SPI with an external Authentication Domain, users must create
an Authentication SPI configuration containing the Authentication SPI name, class name,
and classpath using the SMC.
While configuring an external Authentication Domain, users select a preconfigured
Authentication SPI name and add attributes as name-value pair using the Attribute
Setting dialog box. These attributes are passed to the SPI implementation as a HashMap.
Users can also use the Group Map to map internal groups with external groups.

Authentication SPI Operations on Broker Proxy

Two operations related to the Authentication SPI can be performed on the broker proxy:
● public boolean refreshSecurity(String prefix)
A broker connected to an external Authentication Domain can invoke this operation
to refresh the broker’s security cache. Only credentials of external users are refreshed.
The broker must be in an online state to invoke this operation. This operation is in
com.sonicsw.mq.mgmtapi.runtime.IBrokerProxy.
● public String[ ] getExternalUsers(String param)
A broker connected to an external Authentication Domain can invoke this operation
to get the list of external users cached by the broker. The broker must be in an online
state to invoke this operation.
This operation is in com.sonicsw.mq.mgmtapi.runtime.IBrokerProxy.

Note Changes to the Authentication SPI require recompilation of code in prior release —
Enhancements to the authenticate method require that previously deployed
Authentication SPIs be modified so that they reflect the changes.

Authenticate Method
The signature of the authenticate method is:
public IPasswordUser authenticate(String username,
byte[] credentials,
X509Certificate[] clientCert)
where
■ String username is
the user name that initiated the JMS connection. The user
name can be changed by Login SPI implementation on the client side.

Progress SonicMQ Administrative Programming Guide V7.5 113

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

■ byte[] credentials is the credential retrieved by the broker if it was configured

to get extra credentials from client.
The value of credentials value might be null (or empty byte[ ]) if:
❑ The client did not implement Login SPI
❑ The client returned an empty byte[ ]
❑ The option to get extra credentials from client was not selected on the
Authentication Domain configuration
■ X509Certificate clientCert is the certificates retrieved from the SSL socket
after SSL handshake is successful.

Getting Credentials After Authenticated

When a user is authenticated, it is likely that another communication to get additional
credential is unnecessary. The Authentication SPI interface provides the method public
boolean acquireClientCredentials() in the IAuthentication interface to acquire client
credentials.
After the Authentication SPI class for the broker is loaded in the SonicMQ runtime, the
method void setConfigInfo(java.util.HashMap configuration) is called followed by
calling the method void init(). The init() call makes the Authentication SPI ready for
consumption by the SonicMQ runtime. When that is accomplished, the SonicMQ runtime
calls acquireClientCredentials(). If this method returns true, a second round trip to get
additional credentials is made before every attempted call on the authenticate method.
The credentials acquired are the entire certificate, not just the common name (CN).

Passing Client Certificates to the Broker’s Authentication SPI

The password in the IPasswordUser implementation is not used by the broker. The
mandatory items used by the broker are user name and the groups where the user is a
member. The SonicMQ runtime in this case calls String getName() to get the name of the
user (from java.security.Principal interface) and java.lang.String[] getGroups().
IPasswordUser is a public interface that extends java.security.Principal. It defines three
public methods:
java.lang.String[] getGroups()
byte[] getPassword()
void setGroups(java.lang.String[] groups)

114 Progress SonicMQ Administrative Programming Guide V7.5

 Management SPI

Management SPI
You can use the Management SPI to retrieve a user and group from any third-party
security store. Implementing this SPI results in viewing the read-only users and groups
present on the external security store. The Management SPI provides access to the
following interfaces:
● IManagement — Provides methods to retrieve the user and group from any third party
security store. Located in the package:
com.sonicsw.security.pass.mf.IManagement.
● IGroup — Provides methods to retrieve the name of an external group and a list of
users of that group. Located in the package:
com.sonicsw.security.pass.mf.IGroup.
● INotificationListener — Used by the SonicMQ Directory Service to receive change
notifications regarding any changes in user or group information in the external
security store or domain. Located in the package:
com.sonicsw.security.pass.mf.INotificationListener.
● IEvent — The base interface of all the events that can be used to notify the listener for
any change in users and group information. Located in the package:
com.sonicsw.security.pass.mf.IEvent. Event interfaces can be implemented to
notify the listener of changes in:
■ Groups added, deleted, or modified
■ Users added, deleted, or modified
■ Events discontinued
The following code examples show how to implement the Management SPI for an XML-
based flat file security store. This example uses the Management SPI to retrieve the user
and group information from a third party security store. This code is excerpted from the
sample file:
MQ7.5_install_root\samples\AdvancedSecurity\com\sonicsw\samples\pass
\extAuthDomain\mgmtspi\Management.java

Refer to this file for the complete code sample for implementing the Management SPI.

Progress SonicMQ Administrative Programming Guide V7.5 115

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

The code excerpts demonstrate the following implementation steps:

1. Retrieve user and group information from an external, third party store, in this
example, an XML file. Add the retrieved group name to your data structure, as shown:

public void connect(HashMap configuration) throws ConnectionException

{
if (configuration == null || configuration.size() == 0)
m_configuration = new HashMap();
else
m_configuration = configuration;

String tempStr = (String)configuration.get(MANAGEMENT_SPI_DEBUG);

s_debug = tempStr != null ? (tempStr.equalsIgnoreCase("true") ? true : false) : false;
m_configuration.put(MANAGEMENT_SPI_DEBUG, (s_debug ? "true" : "false"));

tempStr = (String)configuration.get(MANAGEMENT_SPI_TRACE);
s_verbose = tempStr != null ? (tempStr.equalsIgnoreCase("true") ? true : false) : false;
m_configuration.put(MANAGEMENT_SPI_TRACE, (s_verbose ? "true" : "false"));
...
try
{
// read all the users from XML file
String filenameAndLocation = (String) m_configuration.get(USERS_XML);
HashMap users = XMLFileReader.getXMLFileReader().getUsers(filenameAndLocation);

// read all the groups from XML file

filenameAndLocation = (String) m_configuration.get(GROUPS_XML);
HashMap groups = XMLFileReader.getXMLFileReader().getGroups(filenameAndLocation);

// Add group name into user's data structure

XMLFileReader.getXMLFileReader().resolveUsersAndGroups(users, groups);

m_passwordUsers = new IPasswordUser[users.values().size()];

users.values().toArray(m_passwordUsers);

m_groups = new IGroup[groups.values().size()];

groups.values().toArray(m_groups);
...
}
catch (Exception e)
{
throw new ConnectionException(e);
}
}

116 Progress SonicMQ Administrative Programming Guide V7.5

 Management SPI

2. Retrieve a list of groups in the external security store, as shown:

//Retrieve a list of groups that exist in the external security store.

//see com.sonicsw.security.pass.mf.IManagement#getGroups()

public IGroup[] getGroups() throws ConnectionException

{
return m_groups;
}

3. Retrieve a group matching an ID, as shown:

//Retrieve a group that matches the id of a group

//Return the group matching the id.
//see com.sonicsw.security.pass.mf.IManagement#getGroup(java.lang.String)
public IGroup getGroup(String id) throws ConnectionException
{
if (id != null && m_groups != null && m_groups.length > 0)
{
for (int i = 0; i < m_groups.length; i++)
{
IGroup group = m_groups[i];
if (group != null)
{
String groupName = group.getName();

if (groupName != null && groupName.equals(id))

return group;
}
}
}
return null;
}

Progress SonicMQ Administrative Programming Guide V7.5 117

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

4. Convert retrieved groups to the form of IGroups, as shown:

//Get the groups from the XML file and convert them into IGroups

private IGroup[] getGroups(String filenameAndLocation)

{
if (filenameAndLocation == null)
return null;

HashMap groups = XMLFileReader.getXMLFileReader().getGroups(filenameAndLocation);

if (groups != null && groups.size() > 0)

{
ArrayList iGroupArrayList = new ArrayList();

for (Iterator iter = groups.keySet().iterator(); iter.hasNext();)

{
String key = (String) iter.next();
ArrayList list = new ArrayList();

Object o = groups.get(key);
if (o instanceof ArrayList)
{
ArrayList groupMembers = (ArrayList) o;
for (Iterator iterator = groupMembers.iterator(); iterator.hasNext(); )
{
String userName = (String) iterator.next();
if (userName != null)
list.add(new PasswordUser(userName, ""));
}
}
IPasswordUser[] userArray = new PasswordUser[list.size()];
list.toArray(userArray);

iGroupArrayList.add(new Group(key, userArray));

}
IGroup[] iGroups = new Group[iGroupArrayList.size()];
iGroupArrayList.toArray(iGroups);
return iGroups;
}
return null;
}

5. Return a list of users in the external security store, as shown:

//Return the list of users existing in the external domain.

//see com.sonicsw.security.pass.mf.IManagement#getUsers()

public IPasswordUser[] getUsers() throws ConnectionException

{
return m_passwordUsers;
}

118 Progress SonicMQ Administrative Programming Guide V7.5

 Management SPI

6. Return a user matching an ID, and return the user’s credentials, as shown:

//Return a user that matches the id

//Return the user’s credentials
//see com.sonicsw.security.pass.mf.IManagement#getUser(java.lang.String)

public final IPasswordUser getUser(final String id) throws ConnectionException

{
if (id != null && m_passwordUsers != null && m_passwordUsers.length > 0)
{
for (int i = 0; i < m_passwordUsers.length; i++)
{
IPasswordUser user = m_passwordUsers[i];
if (user != null)
{
String userName = user.getName();

if (userName != null && userName.equals(id))

return user;
}
}
return null;
}

7. Convert retrieved users to the form of IPasswordUser, as shown:

//Get the users from the XML file and convert them into IPasswordUser
//Return a list of users

private IPasswordUser[] getUsers(String filenameAndLocation)

{
if (filenameAndLocation == null)
return null;

HashMap users = XMLFileReader.getXMLFileReader().getUsers(filenameAndLocation);

if (users != null && users.size() > 0)

{
ArrayList list = new ArrayList();

for (Iterator iter = users.keySet().iterator(); iter.hasNext();)

{
String key = (String) iter.next();
String value = (String) users.get(key);

IPasswordUser user = new PasswordUser(key, value);

list.add(user);
}

IPasswordUser[] userArray = new PasswordUser[list.size()];

list.toArray(userArray);

return userArray;
}

return null;
}

Progress SonicMQ Administrative Programming Guide V7.5 119

Chapter 5: Using the Advanced Security SPIs for the Sonic Authentication Domains

8. Register event notifications listeners and delete them (if using Management SPI
listeners), as shown:

//Register event notifications listeners.

//see com.sonicsw.security.pass.mf
//.IManagement#setNotificationListener(com.sonicsw.security.pass.mf.INotificationListener)

public boolean setNotificationListener(INotificationListener listener)

{
m_listener = listener;
return true;
}
//Remove/unregister the event notifications listeners.
//see com.sonicsw.security.pass.mf.IManagement#deleteNotificationListener()

public void deleteNotificationListener()

{
m_listener = null;
}
...

9. Disconnect from any connected security store, as shown:

//Disconnect the connection to the external data store

//see com.sonicsw.security.pass.mf.IManagement#disconnect()

public void disconnect()

{
if (m_mgmtSPIEventTransportThread != null)
m_mgmtSPIEventTransportThread.interrupt();
}

The class AdvancedSecurityReloadExternalDomain.java, located in

MQ7.5_install_root\samples\AdvancedSecurity\com\sonicsw\samples\pass
\extAuthDomain\mgmtspi, demonstrates how to use a management operation to reload and
refresh the Management SPI implementation via the Sonic Management Console (SMC).
This operation, performed on the Sonic Directory Service, results in fetching the data
from the external security store and caching that data on the Sonic Directory Server. This
cached data is used by the SMC for configuration purposes only. See
MQ7.5_install_root\samples\readme.htm for more information about this sample.

Also see the chapter “Security Considerations in System Design” in the Progress
SonicMQ Deployment Guide for information about running the advanced security sample
provided with SonicMQ.

120 Progress SonicMQ Administrative Programming Guide V7.5

 Index

A code examples
add a broker to a cluster 35
Activation Daemons 61 add a broker to a container 28
Advanced Security SPIs 101 Configuration API 22
agent 59 configure security 36
agent manager 60 create a container 27
alert notifications 69, 71 create a queue 28
APIs create a route 29
Advanced Security SPIs 101 create HTTP Direct acceptors for a broker 32
Configuration 17 disable Nagle algorithm 41
Directory Service 94 set advanced properties 42
JMX 55 collections monitor 61
proxy 57 command line interface (CLI) sample 78
Runtime 53 commit 21, 25
attributes of notifications compact database
filtering 76 Java sample 88
Authentication SPI 104, 109 Configuration API 17
accessing maps 43
backup broker 20
B broker components 19
certificate revocation list caches 39
broker 19, 63 code examples 22
backup 20 factory connections 20
create configuration 25 fault tolerant connections 20
proxy 113 fault tolerant management components 24
security cache SPI 109 framework components 19
inner classes 43
samples 45
C configuration name 42
certificate revocation list caches connect
configuring 39 to a domain 23
refreshing 63 to fault tolerant management components 24

Progress SonicMQ Administrative Programming Guide V7.5 121

Index

create broker configuration 25

CRLs
G
configuring LDAP servers 39 Group SPI 115
creating the caches 39
refreshing 63
I
D inner classes 43
instance metrics 68
database compaction
Java sample 88
Directory Service 62 J
Directory Service API
changeContext 98 JAAS authentication 108
enable auditing 98 Java
enable configure permissions 99 Configuration API samples 45
enable enforcement 98 proxy API sample 85
enable manage permissions 99 JavaScript
interface 94 Configuration API samples 49
ManagementPermissionsFactory 95 proxy API sample 89
setPermissions 95 JMX
setPrincipal 95 APIs 55
setScope 95 Dynamic MBean sample 78
domain connection 23
L
E LDAP servers
Event SPI 115 for CRLs 40
external Authentication Domain 113 local security store 102
external group SPI 115 logical name 42
external security store 102 Login SPI 103

F M
factory operations 20 manageable components
fault tolerance 20 Configuration API 19
filtering notifications Runtime API 59
Java sample 87 summary 16
JavaScript sample 91 management
flush attributes 63
configurations 21, 26 framework components 19
CRL caches 63 notifications 71
operations 66
management APIs
Configuration 17
Runtime 53

122 Progress SonicMQ Administrative Programming Guide V7.5

 Index

Management SPI 115

metric alert notifications 71
S
metrics 68 sample applications
command line interface (CLI) 78
Configuration API 45
N Java proxy API 85
JavaScript proxy API 89
Notification Listener SPI 115 JMX Dynamic MBean 78
notifications management security command-line
filters 75 interface 97
Runtime API 78
save 21, 25
P Security SPIs 101
PasswordUser SPI 103 security store
pluggable authentication and security external 102
(PASS) 102 internal 102
programming SPIs
using JMX APIs 55 Advanced Security 101
using proxy APIs 57 Authentication 104, 109
proxy APIs 57 broker security cache 109
Event 115
external group 115
R Login 103
Management 115
replication connection 20 Notification Listener 115
rollback 21, 25 PasswordUser 103
Runtime API 53 support, technical 14
agent 59
agent manager 60
alerts 69 T
broker 63
certificate revocation lists, flushing 63 technical support 14
certificate revocation lists, refresh 63 types of notifications
certificate revocation lists, refreshing 63 filtering 76
collections monitor 61
Directory Service 62
instance metrics 68
management attributes 63
management notifications 71
metrics 68
sample applications 78

Progress SonicMQ Administrative Programming Guide V7.5 123

Index

124 Progress SonicMQ Administrative Programming Guide V7.5