tibco hawk™ http adapter - tibco product … hawk concepts guide |vii preface tibco hawk http...

Two-Second Adv

TIBCO Hawk™

HTTP Adapter

User’s GuideSoftware Release 5.1May 2014

antage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO Hawk, TIBCO Designer, TIBCO Rendezvous, TIBCO Enterprise Message Service, TIBCO Runtime Agent, TIBCO Administrator, TIBCO ActiveEnterprise and TIBCO Repository are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1996-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixTIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiiiHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiiiHow to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiiiHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

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

TIBCO Hawk HTTP Adapter Index Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

XML and HTML Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Customizing the Content, Look and Feel of XML Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Schema Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7XSLT/XPATH Stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Cascading Stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8JSP/JSTL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

TIBCO Hawk HTTP Adapter and XML Namespaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10XML Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Qualified Names (QNames) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3 Using the XML Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Relative URL Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Invoking the Relative URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Using Parameters in Relative URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

TIBCO Hawk HTTP Adapter User’s Guide

iv | Contents

Agents URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Alerts URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

MicroAgents URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Invoke URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

XSLT/XPATH Stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33AgentState.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33AgentAlert.xsl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34ClusterView.xsl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35RuleBaseAlert.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35RuleBaseListXml.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Nnames.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Alerts.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37AddRoot.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Ident.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Result.xsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Chapter 4 Using the Sample HTML Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Generating HTML Pages from the XML Stream Using JSTL in JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Sample HTML Interface Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Understanding the Highest Alert State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Customizing the HTML Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Starting the HTML Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Enterprise View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Domain View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Cluster View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Agent Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Alert View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Alert Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Microagent View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Method Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Method Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 5 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64


Contents | v

Appendix A TIBHawkXml Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67getTraceLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68setTraceLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69getTraceParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70setTraceParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71getReleaseVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72_onUnsolicitedMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Appendix B Sample Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Agents.xsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Alerts.xsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

MicroAgents.xsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95


vi | Contents


| vii

Preface

TIBCO Hawk™ HTTP Adapter is yet another web browser-based web application using TIBCO Hawk Console API. It provides much of the same functionality using HTTP as TIBCO Hawk Display or TIBCO Hawk WebConsole. TIBCO Hawk HTTP Adapter facilitates monitoring and managing TIBCO Hawk agents. It provides all of the facilities required to discover agents, monitor agent status, monitor alerts, perform method invocations, and establish method subscriptions.

Topics

• Changes from the Previous Release of this Guide, page viii

• Related Documentation, page ix

• Typographical Conventions, page xi

• Connecting with TIBCO Resources, page xiii

TIBCO Hawk Concepts Guide

viii | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide.

• Updated the JMS jar file that need to be copied for EMS 8.0. See Installation and Configuration on page 16.


Preface | ix

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Hawk DocumentationThe following documents form the TIBCO Hawk documentation set:

• TIBCO Hawk Concepts This manual includes basic descriptions of TIBCO Hawk concepts.

• TIBCO Hawk Installation, Configuration, and Administration Read this book first. It contains step-by-step instructions for installing TIBCO Hawk software on various operating system platforms. It also describes how to configure the software for specific applications, once it is installed. An installation FAQ is included.

• TIBCO Hawk Microagent Reference A reference to the microagents and methods used by a TIBCO Hawk Agent for system and application monitoring.

• TIBCO Hawk WebConsole User’s Guide This manual includes complete instructions for using TIBCO Hawk WebConsole.

• TIBCO Hawk Programmer’s Guide All programmers should read this manual. It contains detailed descriptions of Application Management Interface (AMI), Application Programming Interface (API) concepts, and the TIBCO Hawk security framework and its classes. It also contains detailed descriptions of each class and method for the following APIs:

— AMI API

Java, C++ and C API

— Console API

Java API

— Configuration Object API

Java API

Programmers should refer to the appropriate language reference sections for the AMI API details. The TIBCO Hawk Application Management Interface (AMI) exposes internal application methods to TIBCO Hawk.

• TIBCO Hawk Plug-in Reference Guide Contains details about the Enterprise Message Service, Messaging and JVM microagents methods that are used to administer and monitor the TIBCO Enterprise Message Service server.


x | Related Documentation

• TIBCO Hawk Plug-ins for TIBCO Administrator Contains detailed descriptions of the TIBCO Hawk plug-ins accessed via TIBCO Administrator.

• TIBCO Hawk HTTP Adapter User’s Guide Contains information about performing discovery, monitoring of agent status, monitoring of agent alerts, method invocation, method subscription, and many more activities on TIBCO Hawk and third-party products.

• TIBCO Hawk Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products:

• TIBCO ActiveSpaces®

— TIBCO ActiveSpaces Developer’s Guide

— TIBCO ActiveSpaces Administration

— TIBCO ActiveSpaces Installtion

— TIBCO ActiveSpaces C Reference

• TIBCO Rendezvous®

— TIBCO Rendezvous Concepts

— TIBCO Rendezvous Administration

— TIBCO Rendezvous Configuration Tools

• TIBCO Enterprise Message Service™

— TIBCO Enterprise Message Service Installation

— TIBCO Enterprise Message Service User’s Guide


Preface | xi

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

ENV_HOME

TIBCO_HOME

HAWK_HOME

CONFIG_FOLDER

TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments.

An installation environment consists of the following properties:

• Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu.

• Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME.

TIBCO Hawk installs into a directory within a TIBCO_HOME. This directory is referenced in documentation as HAWK_HOME. The default value of HAWK_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\hawk\5.1.

A TIBCO Hawk configuration folder stores configuration data generated by TIBCO Hawk. Configuration data can include sample scripts, session data, configured binaries, logs, and so on. This folder is referenced in documentation as CONFIG_FOLDER. For example, on Windows systems, the default value is C:\ProgramData\tibco\cfgmgmt\hawk.

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

Use MyCommand to start the foo process.


xii | Typographical Conventions

bold code font Bold code font is used in the following ways:

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

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

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

italic font Italic font is used in the following ways:

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

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

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

Key combinations Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

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

Table 1 General Typographical Conventions (Cont’d)

Convention Use


Preface | xiii

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destinaton for TIBCO customers, partners, and resident experts—a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access All TIBCO DocumentationYou can access TIBCO documentation here:

http://docs.tibco.com/

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

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

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.


http://www.tibcommunity.com

http://docs.tibco.com/

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

https://support.tibco.com

xiv | Connecting with TIBCO Resources


| 1

Chapter 1 Introduction

This chapter describes TIBCO Hawk HTTP Adapter.

Topics

• Introduction, page 2

• TIBCO Hawk HTTP Adapter Index Page, page 4

• XML and HTML Interfaces, page 5

• Customizing the Content, Look and Feel of XML Data, page 6

• TIBCO Hawk HTTP Adapter and XML Namespaces, page 10

• Architecture, page 13


2 | Chapter 1 Introduction

Introduction

TIBCO Hawk HTTP Adapter is a Web application based on the TIBCO Hawk Console API, which facilitates monitoring and management of TIBCO Hawk agents. It allows you to perform discovery, monitoring of agent status, monitoring of agent alerts, method invocation, method subscription, and many more activities on TIBCO Hawk and third-party products. You can also filter the information to view specific data.

TIBCO Hawk HTTP Adapter creates XML output that is viewed by invoking one of the following four relative URLs.

• http://web_server:port/http/Agents

• http://web_server:port/http/Alerts

• http://web_server:port/http/MicroAgents?Agent=value

• http://web_server:port/http/Invoke?Agent=value&MicroAgent=value&Method=value&MAIndex=value

The XML output can also be used by an HTML or other XML-aware application. This allows you to access the data from a wide variety of operating systems and the majority of Web servers, such as Tomcat, WebLogic, and JRUN 4. A sample HTML application that uses the XML data is provided with TIBCO Hawk HTTP Adapter and is described in Chapter 4, Using the Sample HTML Interface.

In addition, TIBCO Hawk HTTP Adapter can be used as a console data provider that can be accessed by other TIBCO Hawk applications using standard HTTP protocol.

TIBCO Hawk HTTP Adapter uses a Java servlet to expand the functionality of the Web server. For more information about servlets, see http://Java.sun.com/Products/servlet/index.htm.

Multiple TIBCO Hawk Domain Support

TIBCO Hawk HTTP Adapter supports the monitoring and management of multiple TIBCO Hawk domains with the same type of transport (that is, TIBCO Rendezvous, TIBCO EMS, or TIBCO DataGrid). It does not support configuring domains with mixed transport types. You can view agent, alert, microagent and method information for all TIBCO Hawk domains in your configuration.


Introduction | 3

TIBCO Hawk Terms

This document assumes that you are familiar with installing and using TIBCO Hawk. The TIBCO Hawk-specific terms shown in TIBCO Hawk HTTP Adapter are not described or explained in this document. Please refer to the TIBCO Hawk documentation for information about TIBCO Hawk.

HTTPS Support

The HTTP Adapter supports HTTPS transport if the web server is configured to accept requests over HTTPS transport. No specific configuration is required on the HTTP Adapter side.



TIBCO Hawk HTTP Adapter Index Page

The format of the starting URL for TIBCO Hawk HTTP Adapter is shown below.

http://web_server:port/http/

The TIBCO Hawk HTTP Adapter index page is shown below. From this page you can do the following:

• Start the sample HTML application, described in Chapter 4, Using the Sample HTML Interface.

• Invoke the Agents URL and Alerts URL. (The MicroAgents URL and Invoke URL have required parameters and cannot be invoked from this page.) The relative URLs are described in Chapter 3, Using the XML Interface.

• View the Agents.xsd, Alerts.xsd, and MicroAgents.xsd schema definitions. These are described in XSLT/XPATH Stylesheets on page 8 and included for reference in Appendix B, Sample Files.

This page also contains links to the TIBCO Support Web site and an overview of TIBCO Support Services.

If the starting URL for your configuration contains special characters, follow the standard encoding rule for URLs.


XML and HTML Interfaces | 5

XML and HTML Interfaces

TIBCO Hawk HTTP Adapter monitors all AMI instrumented applications (microagents) within the configured TIBCO Hawk domains. The data is gathered into an XML stream accessed using the HTTP protocol.

The XML data is viewed in two ways:

• Invoke a relative URL in an XML-aware application. An XML instance document is generated and an XSLT/XPATH stylesheet is applied to it. The data appears as XML instance document. See Chapter 3, Using the XML Interface.

• Retrieve the data as an XML stream and use it in another application, such as the sample HTML application. In the sample HTML application, the XML data is parsed using JSP/JSTL pages and HTML Web pages are generated. The data appears as formatted HTML in a browser. See Chapter 4, Using the Sample HTML Interface.

The two screens below display the same data. The left screen uses the Agents URL and the right screen uses the Agent Status screen in the sample HTML application.

Instructions for using the XML interface are in Chapter 3, Using the XML Interface. Instructions for using the sample HTML application are provided in Chapter 4, Using the Sample HTML Interface.



Customizing the Content, Look and Feel of XML Data

When you invoke a relative URL, the resulting XML stream is saved in HAWK_HOME/webconsole/tomcat/AppData/HawkXml.xml. The raw data in this file is replaced every time you invoke a relative URL.

The data in HawkXml.xml is determined by schema definitions included with TIBCO Hawk HTTP Adapter. These definitions are predefined and cannot be modified, but you can view them to gain an understanding of the structure of HawkXml.xml and the data collected.

You can filter or massage the XML stream in HawkXml.xml to display all, some, or only a small amount of the data: information about only one domain, for example, or for particular agents, types of alerts, or methods in one or multiple domains.

The following types of files allow you to modify the amount and format of data displayed from HawkXml.xml:

• Schema Definitions determine the data in the XML stream. These schema definitions cannot be modified.

• XSLT/XPATH Stylesheets allow you to filter the content of the XML stream and transform it into other formats, such as HTML, PDF, WML, other forms of XML, and so on. These files can be modified and you can create new ones.

• Cascading Stylesheets control the look and feel of the pages in an HTML interface. These can be modified.

• JSP/JSTL Files are JAVA server pages that convert XML content into HTML pages for an HTML interface. These JSPs can be modified.

These files are described in the following sections.


Customizing the Content, Look and Feel of XML Data | 7

Schema DefinitionsThe schema definitions determine the data in the XML stream. These schema definitions cannot be modified.

Agents, Alerts, and Microagents URLs

There are three schema definition files, one each for the Agents, Alerts, and MicroAgents URLs, respectively:

• HAWK_HOME/webconsole/tomcat/webapps/http/xsd/Agents.xsd

• HAWK_HOME/webconsole/tomcat/webapps/http/xsd/Alerts.xsd

• HAWK_HOME/webconsole/tomcat/webapps/http/xsd/MicroAgents.xsd

You can view these schema definitions as files or in Appendix B, Sample Files. You can also display them from the TIBCO Hawk HTTP Adapter Index Page.

Invoke URL

The Invoke URL displays the results of subscribed or invoked methods, so the content varies by method. To allow for this, Invoke uses a framework instead of a static schema definition like the other three relative URLs. The XML stream is generated dynamically by the servlet.

For composite returns (one row of data), all method parameters returned become child elements of <Row>. All data is returned in a root element called <Returns> and each row of data is delimited by <Row> </Row> tags. The format is:

<Returns xmlns="http:\\www.tibco.com\TIBCOHawk"<Row>

<returned_data></Row>

</Returns>

For tabular returns (multiple rows), all method parameters become child elements of the row. The format is:

<Returns xmlns="http:\\www.tibco.com\TIBCOHawk"<Rowset>

<Row><returned_data>

</Row></Rowset>

</Returns>



XSLT/XPATH Stylesheets All four relative URLs retrieve Hawk data in XML. The presentation of the XML data is controlled by stylesheets that use XSLT (eXtensible Stylesheet Language Transformation) and XPath, a language that describes a way to locate and process items in XML. These stylesheets filter and format the XML output to determine the domains, agents, alerts and microagents shown. Each relative URL uses a default stylesheet that displays all elements in your configuration.

These files can be modified and are in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/xsl directory. You can also view the files using an XML-aware application.

Additional sample stylesheets are included with TIBCO Hawk HTTP Adapter. These provide examples of other kinds of formatting and filtering that you can do with the XML data. You can customize any of the existing stylesheets or create new ones to perform such actions as filter data, show only the alerts for particular agents in several domains, or show the status of a selected set of agents in all domains.

To use a customized stylesheet, include the Style parameter in the path when you invoke the relative URL, as described in Relative URL Overview on page 22. All four relative URLs can take the Style parameter.

Cascading StylesheetsThe sample HTML interface uses cascading stylesheets to control the look and feel of the Web pages. These are written using standard HTML and can be modified.

There are two cascading stylesheets used by the sample HTML application. The actual stylesheet used on a particular system depends on the Web server or Web application being used to view the data.

For more information, see Customizing the HTML Application on page 45.

JSP/JSTL FilesJSP/JSTL (Java Server Page/JSP Standard Tag Libraries) files retrieve XML content using the relative URLs, transform the content into HTML, and display the content in HTML. The sample HTML application uses JSP/JSTL. The JSPs can be modified.

All stylesheets must reside in the /xsl directory. If you reference a stylesheet that is not in this directory, a server error occurs.


Customizing the Content, Look and Feel of XML Data | 9

All JSPs for the sample HTML application are in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/jsp directory and can be modified. You can also create new JSPs for a new HTML application.

For more information, see Customizing the HTML Application on page 45 and Generating HTML Pages from the XML Stream Using JSTL in JSP on page 40.



TIBCO Hawk HTTP Adapter and XML Namespaces

A single XML document may contain elements and attributes that are defined for and used by multiple schema, posing the problems of recognition and collision. An XML file referencing those schema needs to be able to identify the particular schema from which an XML element comes from, allowing TIBCO Hawk data and data from other sources to be combined in a document without name collisions. This is possible through the use of universal names whose scope extends beyond their containing document. The XML namespaces mechanism accomplishes this.

There are a number of commercially available books that describe XML and XML namespace. In addition, some of the following text was used with permission from http://www.w3.org/TR/REC-xml-names/.

All data generated by TIBCO Hawk HTTP Adapter is in XML format and is namespace qualified. The URI in the namespace is http://www.tibco.com/TIBCOHawk.

XML NamespacesXML namespaces provide a simple method for qualifying element and attribute names used in XML documents by associating them with namespaces identified by URI references. An XML namespace identifies an XML element as coming from a particular XML schema. This allows multiple XML schemas to use elements with identical names, and an XML file referencing those schemas can easily determine the correct definition for each element.

An XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. XML namespaces differ from the "namespaces" conventionally used in computing disciplines in that the XML version has internal structure and is not, mathematically speaking, a set.

For example, the Marketing.xml schema and the Sales.xml schema may each have an element named <PurchaseOrder>. The namespace adds the schema name to each element, so one element is renamed <Marketing:PurchaseOrder> and the other is renamed <Sales:PurchaseOrder>. An XML file that uses both schemas will not get confused about which <PurchaseOrder> element definition to use.

A namespace is valid for the element it is defined in and for all of the subelements. Subelements can have additional or overriding namespace definitions. A namespace can also contain URIs that refer to XML schema documents not located on the Internet.


TIBCO Hawk HTTP Adapter and XML Namespaces | 11

As an example, the following segment of an XML stream is generated when the Agents URL is invoked. All element names in this sample, such as <Agent> and <AgentName>, belong to the namespace http://www.tibco.com/TIBCOHawk (text is bold for emphasis).

<?xml version="1.0" encoding="UTF-8" ?> - <Agents xmlns="http://www.tibco.com/TIBCOHawk">- <Agent>

<AgentName>Solaris_29</AgentName> <DnsName>tibco.com</DnsName> <HawkDomain>default</HawkDomain> <OsArch>sparc</OsArch> <OsName>SunOS</OsName> <OsVersion>5.9</OsVersion>

.

.

.</Agent>

</Agents>

Qualified Names (QNames)Names from XML namespaces may appear as qualified names (QNames). Any application using the TIBCO Hawk HTTP Adapter XML data stream must use QNames to access the XML elements.

A QName is an element name that has been qualified with a namespace prefix that functions as a placeholder for a namespace URI reference, as shown:

prefix:LocalPart

The prefix provides the namespace prefix part of the QName, and must be associated with a namespace URI reference in a namespace declaration. The LocalPart provides the local part of the qualified name. The combination of the universally managed URI namespace and the document's own namespace produces identifiers that are universally unique.

In TIBCO Hawk HTTP Adapter, the namespace prefix for the URI http://www.tibco.com/TIBCOHawk is th (abbreviation for TIBCO Hawk).

The following sample segment of an XSL stylesheet contains a namespace declaration that specifies two prefixes to represent two URIs:

• xsl represents the URI http://www.w3.org/1999/XSL/Transform.

• th represents the TIBCO Hawk URI, http://www.tibco.com/TIBCOHawk.

In this example, text is bold for emphasis.

<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'xmlns:th='http://www.tibco.com/TIBCOHawk'><xsl:template match="/">



<html><head><title>Total Number of Agents: <xsl:value-of select="count(//th:Agents/th:Agent)"/></title>

</head><BODY BGCOLOR="#FFFFCC" TEXT="#060203"><H1 Align="CENTER">TIBCO Hawk Agent Status</H1>


Architecture | 13

Architecture

Content is served by a single servlet called Agents, which invokes the servlet class COM.TIBCO.hawk.TIBHawkHttp.TIBHawkXml.

There is only one servlet, Agents, in the servlet container. This servlet implements all four relative URLs available in TIBCO Hawk HTTP Adapter: Agents, Alerts, MicroAgents, and Invoke.

The servlet generates all data in XML. The data is then filtered through and formatted by a default or custom XSLT stylesheet. The resulting page is displayed in the browser or served to an XML-aware application.

The architecture of the TIBCO Hawk HTTP Adapter is illustrated below. Figure 1 shows how TIBCO Hawk servlets use the TIBCO Hawk Console API to talk to TIBCO Hawk agents over TIBCO Hawk Transport.

Figure 1 TIBCO Hawk HTTP Adapter Architecture

TIBCO Hawk Transport

TIBCO Hawk agent

TIBCOHawk agent

TIBCO Hawk agent

TIBCOHawk agent

Application Server or Servlet Container

TIBHawkxml

Console API/Invoke

/MicroAgents

/Alerts

/Agents

Browser or HTTP-enabled

Application

XSLT/XPATH Transformation Engine



Figure 2 shows how the XML stream is transformed into HTML for applications such as the sample HTML application included with TIBCO Hawk HTTP Adapter.

Figure 2 Extended Architecture for Generating HTML Interface

The default HTML view uses JSP technology along with JSTL to create HTML pages. The look and feel of the HTML pages can be customized using cascading stylesheets, as described in Customizing the HTML Application on page 45.

TIBCO Hawk Transport

TIBCO Hawk agent

TIBCOHawk agent

TIBCO Hawk agent

TIBCOHawk agent

Application Server or Servlet Container

TIBHawkxml

Console API

HTMLBrowser JSPXSLT/XPATH Transformation Engine


| 15

Chapter 2 Installation

This chapter provides details about TIBCO Hawk HTTP Adapter installtion and configuration.

Topics

• Installation and Configuration, page 16


16 | Chapter 2 Installation

Installation and Configuration

InstallationTIBCO Hawk HTTP Adapter is automatically installed with TIBCO Hawk 5.1. For more detail, please refer to TIBCO Hawk Installation, Configuration, and Administration Guide.

DeploymentTo deploy TIBCO Hawk HTTP Adapter copy the HAWK_HOME/adapters/http directory to the webapps directory of your webserver (HAWK_HOME/webconsole/tomcat/webapps).

ConfigurationIf TIBCO Datagrid is used as the transport, copy the jar (as-common.jar) to the lib folder of Tomcat (HAWK_HOME/webconsole/tomcat/lib).

If TIBCO Rendezvous is used as the transport, copy the following JAR to the lib folder of Tomcat (HAWK_HOME/webconsole/tomcat/lib):

• RV_HOME/lib/tibrvj.jar

If TIBCO Enterprise Message Service is used as the transport, copy the following JARs to the lib folder of Tomcat (HAWK_HOME/webconsole/tomcat/lib):

• EMS_HOME/lib/tibrvjms.jar

• EMS_HOME/lib/tibjms.jar

• EMS_HOME/lib/TIBCrypt.jar

• EMS_HOME/lib/jms.jar (in case of EMS 6.3) or EMS_HOME/lib/jms-2.0.jar (in case of EMS 8.0)

Make sure that TIBCO Datagrid and TIBCO Rendezvous shared libraries are in:

• PATH (Windows)

• LD_LIBRARY_PATH (Linux,Solaris)

• SHLIB_PATH (HP-UX)

• LIBPATH (AIX)

• DYLD_LIBRARY_PATH (mac)


Installation and Configuration | 17

Logging Configuration

The HTTP Adaptor Server uses Log4j based logging to log trace messages in TIBCO Hawk HTTP Adapter server and underlying AMI/Console API Log file configuration is defined in web.xml as follows:

<init-param> <param-name>log4j_config_file</param-name> <param-value>/log4j_http_adapter.properties</param-value></init-param>

AMI Configuration

TIBCO Hawk HTTP Adapter publishes itself as a micoragent (named as TibHawkServlet) using AMI. The AMI configuration for the TIBCO Datagrid transport is same as of the Console API configuration. In case of multiple TIBCO Datagrid domains, TIBCO Hawk HTTP Adapter AMI uses the last TIBCO Datagrid Domain configuration, configured in DomainTransportCfg.xml.

For TIBCO Rendezvous Domains, admin can configure a separate AMI. This is configurable in web.xml.

<init-param>  <param-name>ami_rv_service</param-name> <param-value>7474</param-value></init-param><init-param>  <param-name>ami_rv_network</param-name> <param-value></param-value></init-param><init-param>  <param-name>ami_rv_daemon</param-name> <param-value>tcp:7474</param-value></init-param>

If TIBCO Rendezvous AMI parameters are not configured than the TIBCO Rendezvous Console parameters are used for AMI configuration. In case of multiple TIBCO Rendezvous domains, the last configured TIBCO Rendezvous domain parameters will be used for AMI communication.

For EMS Domain, the AMI communication will use the TIBCO Rendezvous AMI configuration in web.xml. If no TIBCO Rendezvous AMI configuration is configured, then it will use TIBCO Rendezvous AMI with default configuration:

Domain Configuration

To configure a transport for a domain, edit the following parameters in web.xml under the TIBHawkXml definition

<init-param> <param-name>DomainConfigFile</param-name> <param-value>/DomainTransportCfg.xml</param-value></init-param>

The Hawk HTTP Adapter allows easier specification of multiple TIBCO Hawk domains. You can view agent, alert, microagent and method information for all TIBCO Hawk domains in your configuration simultaneously.

The DomainTransportCfg.xml file provides the configuration for the AlertCollector component and specifies the list of TIBCO Hawk domains and their corresponding transports. It follows the xml schema defined as per DomainTransportCfg.xsd. The DomainTransportCfg.xml and DomainTransportCfg.xsd files are located at the HAWK_HOME\adapters\http\WEB-INF\classes folder.

This DomainTransportCfg.xml is an example xml configuration that uses two different transports for two domains. There should be one DomainTransport section per managed domain as shown below.

 <hk:DomainTransport> <hk:HawkDomainName>default</hk:HawkDomainName> <hk:Transport> <hk:RVTransportCfg> <hk:service>7474</hk:service> <hk:network></hk:network> <hk:daemon>tcp:7474</hk:daemon> </hk:RVTransportCfg> </hk:Transport>

Table 2 AMI Default Parameters for TIBCO Rendezvous Transport

Parameter Definition Default Value

Service TIBCO Rendezvous session parameter 7474

Network TIBCO Rendezvous Network parameter ""

Daemon TIBCO Rendezvous Daemon parameter tcp:7474

Installation and Configuration | 19

<hk:SecurityPolicy></hk:SecurityPolicy> </hk:DomainTransport>  <hk:DomainTransport> <hk:HawkDomainName>Hawk1</hk:HawkDomainName> <hk:Transport> <hk:RVTransportCfg> <hk:service>7474</hk:service> <hk:network></hk:network> <hk:daemon>tcp:localhost:7474</hk:daemon> </hk:RVTransportCfg> </hk:Transport> <hk:SecurityPolicy>COM.TIBCO.hawk.security.trusted.Trusted</hk:SecurityPolicy> </hk:DomainTransport>

| 21

Chapter 3 Using the XML Interface

You view the data collected by TIBCO Hawk HTTP Adapter as raw or formatted XML using the four relative URLs, or as formatted HTML using an HTML application.

This chapter describes the XML interface and the XSLT/XPATH stylesheets that format and allow you to customize the XML data. The sample HTML application is described in Chapter 4, Using the Sample HTML Interface.

Topics

• Relative URL Overview, page 22

• Agents URL, page 24

• Alerts URL, page 26

• MicroAgents URL, page 28

• Invoke URL, page 30

• XSLT/XPATH Stylesheets, page 33


22 | Chapter 3 Using the XML Interface

Relative URL Overview

This chapter describes how to invoke the relative URLs and how to use optional and required parameters in the relative URL path.

Invoking the Relative URLsInvoke a relative URL by entering the URL into an XML-aware application. There are four relative URLs available: Agents URL, Alerts URL, MicroAgents URL, and Invoke URL.

The format for each relative URL is:

http://web_server:port/http/relative_url[?param=value&param=value&param=value...]

Each relative URL can take optional parameters. The MicroAgents URL and the Invoke URL each have required parameters. Examples of each relative URL, along with optional and required parameters, are provided later in this chapter.

Invoking Relative URLs from the Index Page

You can also invoke Agents and Alerts from links on the TIBCO Hawk HTTP Adapter Index Page. These pages are invoked using the default stylesheet. After the page is displayed, you can add parameters to the path in the browser’s address field as described later in this chapter. (The MicroAgents URL and Invoke URL have required parameters and cannot be invoked from the index page.)

Using Parameters in Relative URLsThe relative URLs use optional and required parameters. You can include parameters when you first enter the relative URL in the browser’s address field, or invoke the relative URL and then add parameters to the path.

The following considerations apply to parameters in relative URLs:

• Parameter names are case-sensitive.

• To include a parameter, type a ? (question mark) after the relative URL and enter the parameter and its value, separated by = (equal sign).

• If a parameter contains special characters, follow the standard encoding rule for URLs, such as replacing a space with the character + (plus sign).

The relative URL examples in this chapter assume the WAR file was extracted into HAWK_HOME/webconsole/tomcat/webapps.


Relative URL Overview | 23

• Use & (ampersand) between additional parameter pairs.

• You can pass a null value to a parameter by not specifying a value after the = character.

Examples of using optional and required parameters with each relative URL are given later in this chapter.

Order ofParameters

If you are using the optional parameter Style, it is recommended to list it first. The order of any remaining optional or required parameters in the path is not important.

AdditionalParameters

If an optional or required parameter takes additional parameters, you can include them in the relative URL.

For example, the Invoke URL has a required parameter, Method. The method getConfig requires the parameter Interface Name. You can enter the Interface Name parameter with the value hme0 in the Invoke URL as shown (text bold for emphasis):

http://localhost:8081/http/Invoke?Agent=Solaris_26&MicroAgent=Network&MAIndex=0&Method=getConfig&Interface+Name=hme0



Agents URL

Invoking this relative URL generates an XML instance document listing all agents in all of the TIBCO Hawk domains listed in web.xml.

Figure 3 Agents URL Sample Output

Optional Parameters

Optional parameters for the Agents URL are:

• Style A specific XSLT/XPATH stylesheet. If the stylesheet takes parameters, you can include them in the relative URL. If Style is not included, the server uses the default stylesheet, Ident.xsl.

If you specify an optional parameter that does not exist, such as a stylesheet that is not in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl directory, the server returns an error.


Agents URL | 25

Examples

The following relative URL retrieves all agent information from all Hawk domains configured in the web.xml file:

http://localhost:8081/http/Agents

The following relative URL retrieves the same information as above but applies the stylesheet named HighAlert.xsl:

http://localhost:8081/http/Agents?Style=HighAlert.xsl



Alerts URL

Invoking this relative URL generates an XML instance document listing all active alerts and informational messages in all agents in all of the TIBCO Hawk domains listed in web.xml.

Figure 4 Alerts URL Sample Output

Optional Parameters

Optional parameters for the Alerts URL are:



Alerts URL | 27


Example

The following relative URL retrieves information about all active alerts in all configured Hawk domains. Instead of the default stylesheet, it specifies the stylesheet MedAlert.xsl.

http://localhost:8081/http/Alerts?Style=MedAlert.xsl



MicroAgents URL

Invoking this relative URL on a specified agent generates an XML instance document listing the microagents on that agent.

Figure 5 MicroAgents URL Sample Output

Required Parameters

Required parameters for the MicroAgents URL are:

• Agent Name of the agent.

If you do not include a required parameter, the server returns an error.


MicroAgents URL | 29

Optional Parameters

Optional parameters for the MicroAgents URL are:


• Domain A specific TIBCO Hawk domain. If this parameter is not included, the server uses the domain default.

• Micro A microagent and its Instance Identifier, separated by a colon ( : ). If this parameter is not included, the server lists all microagents in the agent.


Examples

Example 1 The following relative URL retrieves information about the Self microagent. The agent is in the default domain in an Agent named Agile.

http://localhost:8081/http/MicroAgents?Agent=Agile&Micro=Self:0

Example 2 The following relative URL retrieves information about all microagents on the Agile Agent in the domain named new.

http://localhost:8081/http/MicroAgents?Agent=Agile&Domain=new

Example 3 The following relative URL retrieves information about the Process microagent with an instance index of 1, on the Agile Agent in the new Hawk domain. Instead of the default stylesheet, it specifies the stylesheet mystyle.xsl.

http://localhost:8081/http/MicroAgents?Agent=Agile&Domain=new&Style=mystyle.xsl&Micro=Process:1



Invoke URL

Invoking this relative URL on a specified agent and microagent invokes or subscribes the specified method on the agent. You can specify either a synchronous or an asynchronous method. A dynamic XML document is generated listing the returned information.

Figure 6 Invoke URL Sample Output

Required Parameters

Required parameters for the Invoke URL are:

• Agent Name of agent

• MicroAgent Name of microagent

• Method Synchronous or asynchronous method to be invoked. If the method takes a parameter, include it in the relative URL. You can pass a null value.

If you do not include a required parameter, the server returns an error.

Optional Parameters

Optional parameters for the Invoke URL are:


• Domain A specific TIBCO Hawk domain. If this parameter is not included, the server uses the domain default.


Invoke URL | 31

• MAIndex (Use this parameter when duplicate instances of the same microagent exist.) A microagent instance index number. The adapter gives the index number 0 to the first instance of each microagent. Additional instances of the same microagent are numbered 1, 2, 3 ... n.

To invoke a method on a specific microagent instance, specify the instance’s index number using this parameter. If this parameter is omitted or included without a value, the server uses a default instance index value of 0.


Examples

Example 1 The following relative URL invokes the method getUptime on the microagent Self with an Instance index of 0 on Agent Solaris_26. Because no domain is specified, the default domain is used. The stylesheet Result.xsl is applied to the document.

http://localhost:8081/http/Invoke?Agent=Solaris_26&MicroAgent=Self&MAIndex=0&Method=getUptime&Style=Result.xsl

Example 2 The following relative URL invokes the getConfig method on the microagent Network with an Instance index of 0. It includes the parameter Interface+Name with an empty value, which returns information on all interfaces in the getConfig method.

http://localhost:8081/http/Invoke?Agent=Solaris_26&MicroAgent=Network&MAIndex=0&Method=getConfig&Interface+Name=

The following relative URL is a slight variation of the previous relative URL. Here, the interface name is specified as hme0.

http://localhost:8081/http/Invoke?Agent=Solaris_26&MicroAgent=Network&MAIndex=0&Method=getConfig&Interface+Name=hme0

Example 3 The following relative URL invokes the getProcess method in the new domain on the rbhatt2-lt agent on the Process microagent with an Instance Index of 0. It retrieves all processes that start with ^t. The expression ^t is represented by the standard encoding %5Et.

http://localhost:8081/http/Invoke?Agent=rbhatt2-lt&Domain=new&MicroAgent=Process&MAIndex=0&Method=getProcess&Process+Name=%5Et

Example 4 The following relative URL is a synchronous subscription to the getInstanceCount method on the Solaris_26 Agent on the Process microagent with an Instance Index of 0. This is a synchronous subscription, not an invocation, because the Interval parameter specifies a subscription interval (5 seconds) and the Subscribe parameter is included with a value of Subscribe.



http://localhost:8081/http/Invoke?Agent=Solaris_26&MicroAgent=Process&MAIndex=0&Method=getInstanceCount&Process+Name=tibhawkhma&Interval=5&Subscribe=Subscribe

This subscription generates the following XML data (bold text for emphasis):

<?xml version="1.0" encoding="UTF-8" ?> "<Returns xmlns="http://www.tibco.com/TIBCOHawk">" <SubscriptionId>4</SubscriptionId> <AgentName>Solaris_26</AgentName> <MicroAgentName>Process</MicroAgentName> <MethodName>getInstanceCount</MethodName> <ResultURL>http://localhost:8081/http/Invoke?Subscription=4</ResultURL> </Returns>

To retrieve the subscription result, invoke the relative URL shown in the <ResultURL> tag. In the example above, you would invoke the relative URL http://localhost:8081/http/Invoke?Subscription=4.

Example 5 The following relative URL subscribes to the onApplicationEvent asynchronous method on the smart Agent in the new TIBCO Hawk domain on the EventLog microagent with an Instance Index of 0. This asynchronous method uses the Source parameter but does not specify a value.

http://localhost:8081/http/Invoke?Agent=smart&Domain=new&MicroAgent=EventLog&MAIndex=0&Method=onApplicationEvent&Source=

A successful subscription generates the following XML data (bold text for emphasis):

<?xml version="1.0" encoding="UTF-8" ?> <Returns xmlns="http://www.tibco.com/http"> <SubscriptionId>2</SubscriptionId> <AgentName>smart</AgentName> <MicroAgentName>EventLog</MicroAgentName> <MethodName>onApplicationEvent</MethodName> <ResultURL>http://localhost:8081/http/Invoke?Subscription=2</ResultURL> </Returns>

To retrieve the subscription result, invoke the relative URL shown in the <ResultURL> tag. In the example above, you would invoke the relative URL http://localhost:8081/http/Invoke?Subscription=2.


XSLT/XPATH Stylesheets | 33

XSLT/XPATH Stylesheets

The default and sample stylesheets included with TIBCO Hawk HTTP Adapter are described in this section, along with tips about customization.

You can write your own stylesheets to customize or filter the XML stream as needed for your configuration. It is a good idea to study a sample stylesheet before modifying it or creating a new stylesheet.

If a stylesheet takes parameters, you can append those parameters to the relative URL path. If the parameters contain special characters (such as a space), follow the standard encoding rule for URLs. For example, enter the parameter Interface Name as Interface+Name. You can pass a null value.

AgentState.xsl

Can Be Applied To:

• Agents URL

Required Parameters:

• AgentState

This stylesheet creates a tabular format containing all agents in a given state, specified by the AgentState parameter value of 1, 2, 3 or 4. The parameter value is received by the TIBHawkXml servlet and then passed to the XSLT transformation engine.

The following line from the AgentState.xsl file identifies this parameter:

<xsl:param name="AgentState"/>

The following code fragment selects all Agent nodes whose RuleBaseEngineState element has the value specified by the parameter AgentState in the relative URL (text bold for emphasis):

<xsl:apply-templates select="//th:Agents/th:Agent[ $AgentState = th:RuleBaseEngineState]"></xsl:apply-templates>

This section assumes you are familiar with XSLT and XPATH standards.

All stylesheets must be in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl directory. If you reference a stylesheet that is not in this directory, the server returns an error.



For each selected Agent node, the Agent template is instantiated, which formats each row of the table.

Example 1 The following relative URL specifies the AgentState.xsl stylesheet, retrieves all agents across all configured Hawk domains which are in state 4 (high alert), and displays the information in tabular format:

http://localhost:8081/http/Agents?Style=AgentState.xsl&AgentState=4

Example 2 The following relative URL specifies the AgentState.xsl stylesheet, displays all agents across all configured Hawk domains which are in state 3 (medium alert), and displays the information in tabular format:

http://localhost:8081/http/Agent?Style=AgentState.xsl&AgentState=3

AgentAlert.xsl

Can Be Applied To:

• Alerts URL

Required Parameter:

• AgentName

Optional Parameter:

• AlertState

This stylesheet retrieves all alerts of a given severity for a given agent. It has one required parameter, AgentName, and one optional parameter, AlertState. If AlertState is not specified, the stylesheet assumes RuleBaseEngine state 4 (high alert).

Example 1 The following example specifies the AgentAlert.xsl stylesheet and retrieves all state 3 (medium) alerts for the agent qaaix03 (text bold for emphasis):

http://localhost:8081/http/Alerts?Style=AgentAlert.xsl&AgentName=qaaix03&AlertState=3



Example 2 The following example specifies the AgentAlert.xsl stylesheet for the agent qaaix03. Because the AlertState parameter is not included in the relative URL, the default alert state of 4 is used and all high alerts are retrieved (text bold for emphasis):

http://localhost:8081/http/Alerts?Style=AgentAlert.xsl&AgentName=qaaix03

ClusterView.xsl

Can Be Applied To:

• Agents URL

Required Parameter:

• ClusterName

This stylesheet creates a tabular format listing all agents belonging to a given cluster, sorted by RuleBaseEngineState in descending order.

Example The following relative URL specifies the ClusterView.xsl stylesheet, retrieves all agents in the SOLARIS cluster, and displays the information in tabular format (bold text for emphasis):

http://localhost:8081/http/Agents?Style=ClusterView.xsl&ClusterName=SOLARIS

RuleBaseAlert.xsl

Can Be Applied To:

• Alerts URL

Required Parameter:

• Rule

This stylesheet creates a tabular format listing all alerts resulting from a given rulebase, from all agents in all configured Hawk domains.



Example The following relative URL specifies the RuleBaseAlert.xsl stylesheet, retrieves all alerts resulting from the AgentLogMonitor-UNIX rulebase in all agents in all configured Hawk domains, and displays the results in tabular format (bold text for emphasis):

http://localhost:8081/http/Alerts?Style=RuleBaseAlert.xsl&Rule=AgentLogMonitor-UNIX

RuleBaseListXml.xsl

Can Be Applied To:

• Agents URL

Required Parameter:

• AgentName

This stylesheet provides an example of generating data in a different format. It generates, in XML format, all loaded rulebases in a given agent. The XML data can be used by any XML-aware application.

Example The following relative URL specifies the RuleBaseList.xsl stylesheet, retrieves all rulebases in the qaisol03 agent, and retrieves the results in XML format (bold text for emphasis):

http://localhost:8081/http/Agents?Style=RuleBaseListXml.xsl&AgentName=qaisol03

Nnames.xsl

Can Be Applied To:

• The JSPs implementing the sample HTML interface

This stylesheet removes the namespace prefix th from all elements and attributes that are namespace qualified with the URI http://www.tibco.com/TIBCOHawk. For more information about namespace, see TIBCO Hawk HTTP Adapter and XML Namespaces on page 10.

This stylesheet is useful when working with parsers that are not namespace aware. After you apply this stylesheet to the data, these parsers can process the data.



Alerts.xsl

Can Be Applied To:

• Alerts URL

Required Parameters:

• AgentState

• Domain

This stylesheet creates a tabular format listing all alerts of a given state from all agents within a given domain. The AgentState parameter value can be 1, 2, 3 or 4 to indicate the RuleBaseEngine state of the Hawk Agent.

Example The following relative URL specifies the Alerts.xsl stylesheet, retrieves all state 3 (medium) alerts from all agents in all configured Hawk domains, and displays the information in tabular format (bold text for emphasis):

http://localhost:8081/http/Alerts?Style=Alerts.xsl&AgentState=3&Domain=default

AddRoot.xsl

Can Be Applied To:

• Any relative URL

This stylesheet is an example of repackaging data in a different format. It adds a new root element called startscrape and removes the namespace declaration from all elements and attributes that are namespace qualified with the URI http://www.tibco.com/TIBCOHawk. For more information about namespace, see TIBCO Hawk HTTP Adapter and XML Namespaces on page 10.

Ident.xsl

Can Be Applied To:

• Any relative URL

This is the default stylesheet used when the Style parameter is not specified in the relative URL. It displays the XML content without filtering, formatting or transforming the original content, and can be used for debugging.



Result.xsl

Can Be Applied To:

• Methoddetail.jsp

This stylesheet presents method invocation and subscription data in tabular format. It allows you to present the data in any form or format required by an application, such as an HTML application.


| 39

Chapter 4 Using the Sample HTML Interface

This chapter describes the sample TIBCO Hawk HTTP Adapter HTML interface.

Topics

• Generating HTML Pages from the XML Stream Using JSTL in JSP, page 40

• Sample HTML Interface Introduction, page 43

• Starting the HTML Interface, page 47

• Enterprise View, page 48

• Domain View, page 49

• Cluster View, page 50

• Agent Status, page 51

• Alert View, page 52

• Alert Details, page 53

• Microagent View, page 54

• Method Details, page 55

• Method Results, page 56


40 | Chapter 4 Using the Sample HTML Interface

Generating HTML Pages from the XML Stream Using JSTL in JSP

The sample HTML interface is an example of transforming the XML stream in HawkXml.xml into a format that can be used by an XML-aware application. This allows the XML data to be easily integrated with any application using XML with HTTP transport.

JSTL is an important specification of the Java Web platform that works with JSP version 1.2 and higher. This section explains how JSTL was used in the file HAWK_HOME/webconsole/tomcat/webapps/http/jsp/alldomain.jsp to create the Enterprise View HTML page. It illustrates the use of JSTL XML and Code tag libraries and expression language to retrieve XML content, parse it, and present in HTML.

You can refer to alldomain.jsp when reading this section. The JSPs are located in the HAWK_HOME/webconsole/tomcat/webapps/http/jsp directory. All JSPs included with TIBCO Hawk HTTP Adapter follow the same programming pattern and are documented in the code.

JSTL

JSTL consists of a collection of tag libraries designed to meet particular needs.

The tag libraries are divided into four groups, available separately:

• Core library (iteration, condition, and so on)

• XML processing library

• Internationalization(i18n) and formatting

• Database (SQL) access

All JSPs make use of the first three tag libraries.

Importing the Tag Libraries

The first step in using JSTL is importing the tag libraries. In the following code fragment from alldomain.jsp, the Core, XML and Internationalization tag libraries are imported.

<%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %><%@ taglib prefix="x" uri="http://java.sun.com/jstl/xml" %><%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %>

This section assumes you are familiar with the use of JSPs (Java Server Pages) and JSTL (JSP Standard Tag Libraries).


Generating HTML Pages from the XML Stream Using JSTL in JSP | 41

Constructing the Relative URL

The following code fragment constructs the relative URL (Agents) to be invoked to retrieve the XML stream, and applies the stylesheet named Nnames.xsl to resulting XML document.

<% if ( aUrl == null ) { aUrl = new StringBuffer( request.getScheme() ); aUrl.append( "://" + request.getServerName() + ":" + request.getServerPort() ); aUrl.append( request.getContextPath() + "/Agents" + "?Style=Nnames.xsl" );

}%>

Importing XML Content

In the following code fragment, the Core library tag is used to import XML content from the Agents URL. The retrieved content is in raw XML text and is stored in a variable named xml.

<C:import var="xml" url="${AURL}" />

Parsing the XML

Raw XML content is not very useful and needs to be parsed. Parsing an XML document converts the raw XML into a format that can be handled with XSLT, XPATH, or other standard XML manipulation technologies.

The following code fragment parses the retrieved XML document and stores the result in a variable named AgentDom. It uses the tag named parse from the XML tag library.

<x:parse var="AgentDom" xml="${xml}" />

Applying a Cascading Stylesheet

After the above line of code, JSP sets up the HTML page and uses the cascading stylesheet named index.css to set the HTML properties.

Retrieving the TIBCO Hawk Agent Data

The following code fragment retrieves the total number of TIBCO Hawk agents in all configured Hawk domains. It uses the XML tag x:out and the XPATH function count. You can use XPATH to select any nodes desired.

Total Agents: <x:out select="count($AgentDom//Agent)" />



Following code iterates through all Agent nodes using the XML tag x:forEach. It also uses the XML tag x:out to retrieve content for the selected nodes and store it in variables.

<x:forEach select="$AgentDom//Agent" >

<c:set var="NameOfDomain" ><x:out select="HawkDomain"/></c:set>

<%--*******************************************************************Setting Up varibale AgentState to "RuleBaseEngineState" node using Xpath.*******************************************************************--%><c:set var="AgentState"><x:out select="RuleBaseEngineState" /></c:set>

<%--*******************************************************************Retrieving from DomainMap, current "State" of Cluster*******************************************************************--%><c:set var="OldAgentState" > <c:out value="${DomainMap[NameOfDomain]}" /></c:set>

…..……..</x:forEach>

All retrieved information is stored in a HashMap named DomainMap, and later shown in tabular format. HashMap stores the domain name as a key and the highest alert state within the domain as a value.


Sample HTML Interface Introduction | 43

Sample HTML Interface Introduction

TIBCO Hawk HTTP Adapter contains a sample HTML application. The XML data is retrieved using four relative URLs as described in the previous chapter. The JSP/JSTL pages format the XML data and generate the HTML Web pages.

This chapter describes the sample HTML application and how to customize it.

NavigationThe HTML application included with TIBCO Hawk HTTP Adapter provides the following views of your TIBCO Hawk environment:

Back and Return

To return to the previous HTML screen, click the browser’s Back arrow.

All pages have a Return to Main page link that takes you back to the TIBCO Hawk HTTP Adapter Index Page.

Table 3 Screens in the Sample HTML Application

Window Name Contents

Enterprise View All TIBCO Hawk domains in the enterprise that are configured in the web.xml file.

Domain View All clusters in the selected domain.

Cluster View All agents in the selected cluster.

Agent Status The current status of the selected agent.

Alert View All current alerts in the selected agent.

Alert Details Full information about the selected alert.

Microagent View All methods in the selected microagent on the selected agent.

Method Details Field(s) for entering method parameters and buttons for Invoke and Subscribe.

Method Results Results of Invoke command, or link to new window displaying Subscribe data.



Understanding the Highest Alert StateMany of the HTML pages contain an alert state indicator in a column titled Highest Alert State. The alert level shown in this column is the highest current alert state in any of the agents in that cluster. Other lower-level alerts and informational messages may also currently exist in the agent; only the highest active alert level is shown in this field.

For example, the following sample Domain View screen shows the clusters in the TIBCO Hawk domain named default.

In this domain, the following alert conditions currently exist:

• The LINUX and AIX clusters each have one agent. Each agent currently has a High alert, and neither agent is expired. Each agent may also currently have Medium or Low alerts, or an informational message. You can click on either cluster name to view the current status of the agent and information about the current alerts or messages.

• The 999.999.999.0 cluster has one agent, and there are currently no alerts in that agent. There may be informational messages. You can click on the cluster name to view the status of the agent.

• The SOLARIS cluster has one agent with at least one Medium alert. There may also be one or more Low alerts or informational messages in the agent. You can click on the cluster name to view the status of the agent in the SOLARIS cluster and display information about the alerts and messages.

The presence of informational messages is not indicated in the Highest Alert State column. To determine if an agent has an informational message, display the Alert Details view.


Sample HTML Interface Introduction | 45

Customizing the HTML ApplicationYou can customize the data displayed along with the look and feel of the HTML application by modifying the following files. These files are written using standard HTML. The XML stream is formatted using JSP/JSTL and XSLT stylesheets.

Cascading Stylesheets

The look and feel of the HTML pages is controlled by a cascading stylesheet. TIBCO Hawk HTTP Adapter contains two cascading stylesheets, one for JRun4 and one for all other supported Web servers. Modify the correct file for the Web server used in your configuration.

• JRun4: HAWK_HOME/webconsole/tomcat/webapps/http/jsp/css/index.css

• All other supported Web servers: HAWK_HOME/webconsole/tomcat/webapps/http/css/index.css

Refresh Interval

Each JSP has a default refresh interval of 15 seconds. You can customize the refresh interval for each JSP by modifying the appropriate parameter in the file HAWK_HOME/webconsole/tomcat/webapps/http/WEB-INF/web.xml.

Date and Time Updated

The date and time that the information on each screen was last updated is shown at the bottom of each screen. You can customize the display format by modifying the file HAWK_HOME/webconsole/tomcat/webapps/http/jsp/HawkTime.jsp.

JSPs

The following JSP and XSL files control the parsing of XML data for each HTML Web page.

It is a good idea to study the existing file before making changes. Always work on a copy of the original file.

Table 4 Location of Files for Parsing XML Data into HTML

HTML Page JSP or XSL File

Enterprise View HAWK_HOME/webconsole/tomcat/webapps/http/jsp/alldomain.jsp

Domain View HAWK_HOME/webconsole/tomcat/webapps/http/jsp/hawkdomain.jsp



Alert State Colors and Conditions

The following table lists the default HTML color scheme for the TIBCO Hawk HTTP Adapter alert states. To change the default colors, modify the file HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/jsp/HawkAlert.jsp .

Cluster View HAWK_HOME/webconsole/tomcat/webapps/http/jsp/clusterview.jsp

Agent Status HAWK_HOME/webconsole/tomcat/webapps/http/jsp/dtagentview.jsp

Alert View HAWK_HOME/webconsole/tomcat/webapps/http/jsp/alertview.jsp

Alert Details HAWK_HOME/webconsole/tomcat/webapps/http/jsp/dtalertview.jsp

Microagent View HAWK_HOME/webconsole/tomcat/webapps/http/jsp/microagent.jsp

Method Details HAWK_HOME/webconsole/tomcat/webapps/http/jsp/methoddetail.jsp

Method Results HAWK_HOME/webconsole/tomcat/webapps/http/xsl/result.xsl

Table 4 Location of Files for Parsing XML Data into HTML (Cont’d)

HTML Page (Cont’d) JSP or XSL File (Cont’d)

Table 5 Default Alert Colors for Sample HTML Application

Color Meaning

Purple Agent expired

Red High alert state

Orange Medium alert state

Yellow Low alert state

Green No alert


Starting the HTML Interface | 47

Starting the HTML Interface

Display the index page, as described in TIBCO Hawk HTTP Adapter Index Page on page 4. The index page is shown below.

To start the sample HTML interface, click the HTML Interface: TIBCO Hawk Enterprise View link. The Enterprise View is displayed, as described in the next section.



Enterprise View

In the Enterprise view, you see an overview of all monitored TIBCO Hawk domains in your enterprise.

The Hawk Domain column lists the names of the domains being monitored. The Highest Alert State column indicates the highest current alert state in each domain, and the Number of Agents column indicates how many agents are in each domain.

For example, the sample screen above indicates:

• There are two TIBCO Hawk domains being monitored, one named default and one named new.

• There are a total of five agents in these two domains.

— The default domain contains four agents.

— The new domain contains one agent.

• In the default domain, at least one agent has a High alert. Other agents in the default domain may also have High alerts. They may also have Medium or Low alerts or informational messages. None of the agents in the default domain are Expired.

• The agent in the new domain does not have any active alerts. It may have informational messages.

Click the name of a domain to view information about the clusters in that domain. The Domain View appears, described in the next section.


Domain View | 49

Domain View

This view appears when you click a domain name in the Enterprise View. It displays information about the clusters in the selected domain.

The Cluster column lists the names of the clusters in the domain. The Highest Alert State column shows the highest alert state of any agent in each cluster, and the Agents in Cluster column indicates how many agents are in each cluster.

For example, the sample screen above indicates that:

• The listed clusters belong to the TIBCO Hawk domain named default.

• There are four clusters in this domain: LINUX, AIX, 999.999.999.0 and SOLARIS.

• There are a total of four agents in these clusters, one in each cluster.

• The agent in the 999.999.999.0 cluster does not currently have any alerts, although it may have an informational message.

• The agent in the LINUX cluster and the agent in the AIX cluster have at least one active High alert each. They may also have one or more Medium or Low alerts or informational messages.

• The highest current alert in the SOLARIS cluster is a Medium alert. There are no High alerts in the SOLARIS cluster, but there may be Low alerts or informational messages.

To view information about the agents and alerts in each domain, click the domain name. The Cluster View appears, described in the next section.



Cluster View

This screen appears when you click a cluster name in the Domain View. It displays information about the agents in the selected cluster.

The Agent Name column lists the names of the agents in the cluster. The Highest Alert State column shows the highest alert state in that agent, and the O.S. Name column indicates the operating system that the agent is running on.

For example, the sample screen above indicates that:

• The agent listed on this screen belongs to the LINUX cluster in the TIBCO Hawk default domain.

• The LINUX cluster contains only one agent, named hk-lnx02.

• The hk-lnx02 agent currently has at least one High alert. It may also have one or more Medium or Low alerts or informational messages.

• The hk-lnx02 agent is running on the LINUX operating system.

You can click the agent name to display the Agent Status, or click the alert state to display the Alert View. These views are discussed in the next sections.


Agent Status | 51

Agent Status

This screen displays information about the selected agent. The fields on this screen are described in the TIBCO Hawk Administrator’s Guide.

This screen also allows you to view the microagents on this agent. For more information, see Microagent View on page 54.

For example, the sample screen above displays the current status of the hk-lnx02 agent, belonging to the LINUX cluster in the TIBCO Hawk default domain. The highest current alert level in this agent is High. It may also have one or more Medium or Low alerts or informational messages.

To display the Alert View for this agent, click the alert level. This displays the same screen as clicking the highest alert level for this agent in the Cluster View.



Alert View

This screen is displayed when you click an alert level in the Cluster View or when you click the alert level in the Agent Status. The error and warning messages on this screen are explained in the TIBCO Hawk Administrator’s Guide.

For example, the sample screen above displays some of the current alerts for the hk-lnx02 agent, belonging to the LINUX cluster in the TIBCO Hawk default domain. You may need to scroll to see the highest alert(s).

To see more information about a particular alert or informational message, click the alert state in the first column. The Alert Details screen appears, described in the next section.


Alert Details | 53

Alert Details

This screen appears when you click an alert level on the Alert View screen. The fields on this screen are described in the TIBCO Hawk Administrator’s Guide.

For example, the sample screen above displays details for a High alert in the hk-lnx02 agent, in the TIBCO Hawk default domain.

To return to the previous view, click the browser’s Back button.



Microagent View

The Microagent View displays the methods associated with a microagent selected in the Agent Status view.

To view the list of methods in a microagent, display the Agent Status view, select a microagent from the drop-down list, and click Select. The list of available microagents varies depending on your configuration. In the sample screen below, FileSystem:0 has been selected.

When you click Select, the Microagent View appears.

The sample screen above displays the methods associated with the HawkEventService microagent.

To view information about a specific method, click on the method name. This displays the Method Details view, described in the next section.


Method Details | 55

Method Details

This view displays the parameters in the method selected in the Microagent View. The available parameters for the method vary depending on the method signature.

The sample screen above shows the getByMountPoint synchronous method in the FileSystem:0 microagent, in the hk-lnx02 agent.

Fill in the parameter(s) and click Subscribe or Invoke, as desired.

• Invoke invokes the method on the microagent. This option is available with synchronous and asynchronous methods.

• Subscribe subscribes to the method. This option is available only with synchronous methods.

Each option displays the Method Results view, described in the next section.



Method Results

This view appears when you click Invoke or Subscribe in the Method Details view.

• Invoke (synchronous method) returns this page with the result. The value is not updated. To return to the previous view, click the browser’s Back button.

• Invoke (asynchronous method) or Subscribe (synchronous method) returns this page with a link to open a new browser window. The new window is refreshed every five seconds with the current value of the method, independent of the Data Delivery Interval specified in the Method Details view.

You can leave this browser window open while you continue to work in the sample HTML interface. TIBCO Hawk HTTP Adapter terminates the subscription or invocation five minutes after one of the following happens:

— You close this browser window.

— The window has stopped fetching values.

The look and feel of these screens can be customized using index.css and Result.xsl as described in Customizing the HTML Application on page 45.

The sample screen above shows the Method Results window for an Invoke (synchronous method) request.


Method Results | 57

The sample screen above shows the Method Results window for an Invoke (asynchronous method) or Subscribe (synchronous method) request. Click Click here for Result to open a new browser window.

The sample screen above shows the new browser window containing data for the selected method.


| 59

Chapter 5 Security

This chapter describes the security aspects of TIBCO Hawk HTTP Adapter.

Topics

• Security Overview, page 60

• Authentication, page 61

• Authorization, page 64


60 | Chapter 5 Security

Security Overview

Security is an important aspect of applications that transport sensitive data over the Internet. Because of this requirement, the Java Servlet 2.2 and JSP 1.2 specifications require the Web server or application server to implement the following security capabilities:

• Basic and digest authentication, as defined in the HTTP/1.1 specifications.

• Form-based security that allows developers to control the look and feel of login screens.

• Declarative authentication.

Web servers or application servers may provide SSL and client certificate authentication, although containers that are not J2EE-compliant are not required to do so.

TIBCO Hawk HTTP Adapter supports all of these security mechanisms. It uses container-provided authentication and, like TIBCO Hawk Display, it uses the TIBCO Hawk Trusted model for authorization. TIBCO Hawk HTTP Adapter can be easily be integrated into an existing authentication environment.


Authentication | 61

Authentication

A servlet-based Web application can choose from the following types of authentication, from least secure to most:

1. Basic authentication

2. Form-based authentication

3. Digest authentication

4. SSL and client certificate authentication

TIBCO Hawk HTTP Adapter relies upon declarative authentication. This requires no programming because authentication is declared with XML tags in the Web application’s deployment descriptor (HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/WEB-INF/web.xml) and implemented by the Web server or application server.

Each TIBCO Hawk HTTP Adapter can use the most appropriate method for authenticating users. This section discusses implementing declarative authentication on the Tomcat Web server as an example. Refer to your Web server’s or application server’s documentation for more information.

Basic Authentication Basic authentication is defined by the HTTP/1.1 specification. When a client attempts to access a protected resource, the server prompts for a username and password. If the server can authenticate the username and password, access is granted to the resource; otherwise, the process repeats a specific number of times. Although basic and form-based authentication is not secure, you can use in combination with SSL for secure transport.

Users and Roles

The following code fragment from the web.xml file restricts access to the Web resources /Agent and /Alerts to members of the HawkUser role. Access to /Invoke and /MicroAgents is restricted to members of the HawkAdmin role.

The authentication mechanism is specified as basic. Passwords are transmitted with base64 encoding, which provides no encryption. A Web administrator can use digest authentication instead of basic authentication, in which a hash value of password is transmitted instead of base64 encoded format.

<web-app><!-- Security constraint for TIBCO Hawk Servlet


<security-constraint> <web-resource-collection> <web-resource-name>HawkSecure</web-resource-name> <description>TIBCO Hawk Security</description> <url-pattern>/Agents</url-pattern> <url-pattern>/Alerts</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <description>"HawkUser" Role, users belongs to this role are only allowed to access this resource </description> <role-name>HawkUser</role-name> </auth-constraint>

</security-constraint>

<security-constraint> <web-resource-collection> <web-resource-name>HawkAdmin</web-resource-name> <description>TIBCO Hawk Power User</description> <url-pattern>/Invoke</url-pattern> <url-pattern>/MicroAgents</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <description>"HawkAdmin" Role, users belongs to this role are only allowed to access this resource </description> <role-name>HawkAdmin</role-name> </auth-constraint>


<login-config> <auth-method>BASIC</auth-method> </login-config> </web-app>

For the Tomcat Web server, usernames and passwords are associated with roles in $TOMCAT_HOME/conf/tomcat-users.xml. An excerpt from this configuration file is shown below.

<tomcat-users> <user name="hawk" password="hawkhttp" roles="HawkUser"/> <user name="hawk1" password="hawk1http" roles="HawkUser, HawkAdmin"/></tomcat-users>


Authentication | 63

This excerpt shows that the username hawk with the password hawkhttp is bound to one role HawkUser. The user hawk1 with the password hawk1http is bound to two roles, HawkUser and HawkAdmin.

Because of the role access privileges defined in the web.xml excerpt shown previously, the authenticated user hawk can only access the /Agent and /Alerts Web resource. The authenticated user hawk1 belongs to both roles and can access all four Web resources.

Realms

A realm is a group of usernames and passwords that identify valid users of Web applications (or set of Web applications), along with each user’s roles. Roles serve a similar purpose to groups in UNIX, as access to specific Web application resources are granted to all users belonging to a particular role. A user can belongs to more than one role.

It is often desirable to link a Web server or application server to an existing authentication database or other mechanism. Although the servlet specification describes a portable mechanism for Web applications to declare their security requirements, there is no portable API interface defining the interface between the Web server or application server and the associated user and role information.

As a result, Tomcat Web server defines a Java interface, org.apache.Catalina.Realm, that can be implemented by plug-in components to establish this connection. Three standard plug-ins are provided with Tomcat4.x, supporting connections to three different sources of authentication information:

• MemoryRealm accesses authentication information stored in an in-memory object collection initialized from an XML document (conf/tomcat-users.xml). This is the default Tomcat Web server mechanism.

• JDBCRealm uses a JDBC driver to access authentication information stored in a relational database.

• JNDIRealm uses a JNDI provider to access authentication information stored in an LDAP-based directory server.

The $TOMCAT_HOME/conf/server.xml file specifies the default realm org.apache.Catalina.realm.MemoryRealm in. This file is shared by all contexts (Web applications). If the Tomcat Web server administrator selects an authentication mechanism other than MemoryRealm, the corresponding change should be made in the serverl.xml file.



Authorization

TIBCO Hawk HTTP Adapter implements a Trusted model of authorization, similar to TIBCO Hawk Display. Refer to Chapter 8, Security, in TIBCO Hawk Installation and Configuration, for more information.

To enable all TIBCO Hawk domains monitored by TIBCO Hawk HTTP Adapter to use the Trusted model, perform the following steps:

1. Stop the Web server or application server.

2. Open the file HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/WEB-INF/classes/DomainTransportCfg.xml for editing.

3. Specify the security policy for a particular domain under the <hk::SecurityPolicy> tag.

4. Restart the Web server or application server.

The following code fragment shows the SecurityPolicy parameter in the DomainTransportCfg.xml file:

<hk::SecurityPolicy> COM.TIBCO.hawk.security.trusted.Trusted</hk::SecurityPolicy>

Missing dll Error

On Microsoft Windows, if HawkTrustedUserId.dll is not in the path of the Web server or application server, the following error message appears in the server’s log file:

2003-05-15 12:04:48 Agents: Using Security Policy: COM.TIBCO.hawk.security.trusted.Trusted 2003-05-15 12:04:48 Agents: java.lang.UnsatisfiedLinkError: no HawkTrustedUserID in java.library.path

The following error message also appears on the server console:

ERROR : Unable to load HawkTrustedUserID - no HawkTrustedUserID in java.library. path ## Thu May 15 12:04:48 PDT 2003 ##

When the security model is implemented on two applications (such as, Hawk HTTP Adaptor and Hawk WebConsole), then it is recommended that each application is deployed on a different instance of the web container (such as, Tomcat).


Authorization | 65

Implementing Own Java Security Class

If you are implementing your own Java Security class instead of using Trusted implementation (discussed in Chapter 6 of the TIBCO Hawk Programmer’s Guide), you must specify the class in web.xml and the SecurityPolicy element file. Also make this class available to TIBCO Hawk HTTP Adapter.

The Java class file can be jarred and copied to HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/WEB-INF/lib. Restart the Web server or application server to make the new change effective.


| 67

Appendix A TIBHawkXml Microagent Methods

This appendix describes the methods associated with the TIBHawkXml microagent.

Topics

• getTraceLevel(), page 68

• setTraceLevel(), page 69

• getTraceParameters(), page 70

• setTraceParameters(), page 71

• getReleaseVersion(), page 72

• _onUnsolicitedMsg(), page 73


68 | Appendix A TIBHawkXml Microagent Methods

getTraceLevel()Method

Description This method returns the current trace level settings.

Parameters None.

Returns

Remarks Each trace level can be set to On (enabled), or Off (disabled).This method uses synchronous method invocation.

The default setting has Information, Warning, and Error trace categories enabled. These are the proper categories to have enabled in a production environment. The Debug, AMI, and Publisher categories are specifically designed to troubleshoot problems and should only be enabled when trying to diagnose a problem.

Name Description

Information Current information trace setting, represented as a String.

Warning Current warning trace setting, represented as a String.

Error Current error trace setting, represented as a String.

Debug Current debug trace setting, represented as a String.

AMI Current AMI trace setting, represented as a String.

Publisher Current Publisher trace setting, represented as a String.


setTraceLevel() | 69

setTraceLevel()Method

Description This method sets the trace level settings.

Parameters

Each trace level can be set to On (enabled), Off (disabled), or Current (leave current setting as is).

Returns

Remarks Each trace level can be set to On (enabled), or Off (disabled).This method uses synchronous method invocation.

The default setting has Information, Warning, and Error trace categories enabled. These are the proper categories to have enabled in a production environment. The Debug, AMI, and Publisher categories are specifically designed to troubleshoot problems and should only be enabled when trying to diagnose a problem.

Name Description

Information Information trace setting, represented as a String.

Warning Warning trace setting, represented as a String.

Error Error trace setting, represented as a String.

Debug Debug trace setting, represented as a String.

AMI AMI trace setting, represented as a String.

Publisher Publisher trace setting, represented as a String.

Name Description

Information Information trace setting, represented as a String.

Warning Warning trace setting, represented as a String.

Error Error trace setting, represented as a String.

Debug Debug trace setting, represented as a String.

AMI AMI trace setting, represented as a String.

Publisher Publisher trace setting, represented as a String.



getTraceParameters()Method

Description This method modifies the current trace configuration.

Parameters

Use string Current for keeping the current setting for string parameters and use integer value 0 for keeping the current setting for integer parameters.

Returns

Name Description

Directory The trace file directory path where trace log file should be kept, represented as a String.

File Name The trace file name, represented as a String.

Max File Size Trace file maximum size before it is rolled over in Kbytes, represented as an integer.

Max Trace File The maximum number of trace file to keep in the trace directory, represented as an integer.

Name Description

Directory The current trace file directory path where trace log file should be kept, represented as a String.

File Name The current trace file name, represented as a String.

Max File Size The current trace file maximum size before it is rolled over in Kbytes, represented as an integer.

Max Trace File The current maximum number of trace file to keep in the trace directory, represented as an integer.


setTraceParameters() | 71

setTraceParameters()Method

Description This method modifies the current trace configuration.

Parameters


Returns

Name Description

Directory The trace file directory path where trace log file should be kept, represented as a String.

File Name The trace file name, represented as a String.

Max File Size Trace file maximum size before it is rolled over in Kbytes, represented as an integer.

Max Trace File The maximum number of trace file to keep in the trace directory, represented as an integer.

Name Description

Directory The current trace file directory path where trace log file should be kept, represented as a String.

File Name The current trace file name, represented as a String.

Max File Size The current trace file maximum size before it is rolled over in Kbytes, represented as an integer.

Max Trace File The current maximum number of trace file to keep in the trace directory, represented as an integer.



getReleaseVersion()Method

Description This method returns version information about the current release of this microagent.

Parameters None.

Returns

Remarks This method uses synchronous method invocation.

Name Description

Name The name of the application, represented as a String, which implements this microagent.

Version The release version, represented as a String.

Date The release date, represented as a String.

Major The release version major number, represented as an integer.

Minor The release version minor number, represented as an integer.

Update The release version update number, represented as an integer.


_onUnsolicitedMsg() | 73

_onUnsolicitedMsg()Method

Description This method returns any unsolicited notifications that are sent from this microagent.

Parameters None.


Remarks Invoking this method returns the last such message that was received (if any). An unsolicited message is an information, warning, or error message that is sent directly to the manager.

Returns Name Description

TYPE Returns a string of either INFO, WARNING, or ERROR.

TEXT The text of the message.

ID A number, that is an integer, used by the application to identify the message.

INBOX An inbox address, represented as a string, used to send the message.


| 75

Appendix B Sample Files

This appendix contains listings of the web.xml file and the default schema definitions included with TIBCO Hawk HTTP Adapter.

Topics

• web.xml, page 76

• Agents.xsd, page 85

• Alerts.xsd, page 88

• MicroAgents.xsd, page 92


76 | Appendix B Sample Files

web.xml

This file is the sample deployment descriptor for TIBCO Hawk HTTP Adapter. It is located in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/WEB-INF directory.

The commented lines contain entries for monitoring multiple TIBCO Hawk domains. See Configuration on page 16 for more information.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app> <servlet> <servlet-name> Agents </servlet-name> <servlet-class> COM.TIBCO.hawk.TIBHawkHttp.TIBHawkXml </servlet-class>   <init-param> <param-name>DomainConfigFile</param-name> <param-value>/DomainTransportCfg.xml</param-value> </init-param>

<init-param> <param-name>AgentExpiredRetentionPeriod</param-name> <param-value>15</param-value> </init-param>

<init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param>

<init-param><param-name>log4j_config_file</param-name><param-value>/log4j_http_adapter.properties</param-value></init-param>

<init-param><param-name>ami_rv_service</param-name><param-value>7474</param-value></init-param>

web.xml | 77

<init-param><param-name>ami_rv_network</param-name><param-value></param-value></init-param><init-param><param-name>ami_rv_daemon</param-name><param-value>tcp:7474</param-value></init-param>

<load-on-startup> 1 </load-on-startup></servlet>

<servlet> <servlet-name> HawkTime </servlet-name> <description> JSP page for first hawkdomain.jsp </description> <jsp-file> /jsp/HawkTime.jsp </jsp-file> <load-on-startup> 3 </load-on-startup></servlet>

<servlet> <servlet-name> HawkAlert </servlet-name> <description> JSP page for first hawkdomain.jsp </description> <jsp-file> /jsp/HawkAlert.jsp </jsp-file> <load-on-startup> 2 </load-on-startup></servlet>

<servlet> <servlet-name> alldomain </servlet-name> <description> JSP page for first alldomain.jsp </description> <jsp-file> /jsp/alldomain.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 4 </load-on-startup>


</servlet>

<servlet> <servlet-name> hawkdomain </servlet-name> <description> JSP page for first hawkdomain.jsp </description> <jsp-file> /jsp/hawkdomain.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 5 </load-on-startup></servlet>

<servlet> <servlet-name> clusterview </servlet-name> <jsp-file> /jsp/clusterview.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 6 </load-on-startup></servlet>

<servlet> <servlet-name> alertview </servlet-name> <jsp-file> /jsp/alertview.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 7 </load-on-startup></servlet>

<servlet> <servlet-name> dtagentview </servlet-name> <jsp-file> /jsp/dtagentview.jsp


web.xml | 79

</jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 8 </load-on-startup></servlet>

<servlet> <servlet-name> dtalertview </servlet-name> <jsp-file> /jsp/dtalertview.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 9 </load-on-startup></servlet>

<servlet> <servlet-name> microagent </servlet-name> <jsp-file> /jsp/microagent.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 10 </load-on-startup></servlet>

<servlet> <servlet-name> methoddetail </servlet-name> <jsp-file> /jsp/methoddetail.jsp </jsp-file> <init-param> <param-name>RefreshInterval</param-name> <param-value>15</param-value> </init-param> <load-on-startup> 11 </load-on-startup></servlet>



<servlet-mapping> <servlet-name> HawkTime </servlet-name> <url-pattern> /HawkTime </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> HawkTime </servlet-name> <url-pattern> /jsp/HawkTime </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> HawkAlert </servlet-name> <url-pattern> /HawkAlert </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> HawkAlert </servlet-name> <url-pattern> /jsp/HawkAlert </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> hawkdomain </servlet-name> <url-pattern> /hawkdomain </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> alldomain </servlet-name> <url-pattern> /alldomain </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name>


web.xml | 81

clusterview </servlet-name> <url-pattern> /clusterview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> clusterview </servlet-name> <url-pattern> /jsp/clusterview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> alertview </servlet-name> <url-pattern> /alertview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> alertview </servlet-name> <url-pattern> /jsp/alertview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> dtagentview </servlet-name> <url-pattern> /dtagentview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> dtagentview </servlet-name> <url-pattern> /jsp/dtagentview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> dtalertview </servlet-name> <url-pattern>



/dtalertview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> dtalertview </servlet-name> <url-pattern> /jsp/dtalertview </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> microagent </servlet-name> <url-pattern> /microagent </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> microagent </servlet-name> <url-pattern> /jsp/microagent </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> methoddetail </servlet-name> <url-pattern> /methoddetail </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> methoddetail </servlet-name> <url-pattern> /jsp/methoddetail </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> Agents </servlet-name> <url-pattern> /Agents </url-pattern> </servlet-mapping>


web.xml | 83

<servlet-mapping> <servlet-name> Agents </servlet-name> <url-pattern> /Alerts </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> Agents </servlet-name> <url-pattern> /Invoke </url-pattern> </servlet-mapping>

<servlet-mapping> <servlet-name> Agents </servlet-name> <url-pattern> /MicroAgents </url-pattern> </servlet-mapping>

<taglib> <taglib-uri>http://java.sun.com/jstl/core</taglib-uri> <taglib-location>/WEB-INF/c.tld</taglib-location> </taglib>

<taglib> <taglib-uri>http://java.sun.com/jstl/xml</taglib-uri> <taglib-location>/WEB-INF/x.tld</taglib-location> </taglib>

<taglib> <taglib-uri>http://java.sun.com/jstl/fmt</taglib-uri> <taglib-location>/WEB-INF/fmt.tld</taglib-location> </taglib>

<!--Security constraints for Hawk Servlets

<security-constraint> <web-resource-collection> <web-resource-name>HawkSecure</web-resource-name> <description>TIBCO Hawk Security</description> <url-pattern>/Agents</url-pattern> <url-pattern>/Alerts</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint>


<description>"HawkUser" Role, users are only allowed to access this resource </description> <role-name>HawkUser</role-name> </auth-constraint>


<security-constraint> <web-resource-collection> <web-resource-name>HawkAdmin</web-resource-name> <description>TIBCO Hawk Power User</description> <url-pattern>/Invoke</url-pattern> <url-pattern>/MicroAgents</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <description>"HawkAdmin" Role, users are only allowed to access this resource </description> <role-name>HawkAdmin</role-name> </auth-constraint>


<login-config> <auth-method>BASIC</auth-method> </login-config>

--></web-app>


Agents.xsd | 85

Agents.xsd

This is the schema definition for the Agents URL. It is located in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/xsd directory.

<?xml version = "1.0" encoding = "UTF-8"?><schema xmlns = "http://www.w3.org/2001/XMLSchema" targetNamespace = "http://www.tibco.com/TIBCOHawk" xmlns:Hawk = "http://www.tibco.com/TIBCOHawk" xmlns:xsd = "http://www.w3.org/2001/XMLSchema"> <element name = "Agents"> <complexType> <sequence minOccurs = "0" maxOccurs = "unbounded"> <element ref = "Hawk:Agent"/> </sequence> </complexType> </element> <element name = "Agent"> <complexType> <choice> <element ref = "Hawk:AgentName"/> <element ref = "Hawk:AgentMajorVersion"/> <element ref = "Hawk:AgentMinorVersion"/> <element ref = "Hawk:AgentUpdateVersion"/> <element ref = "Hawk:AgentCluster"/> <element ref = "Hawk:DnsName"/> <element ref = "Hawk:HawkDomain"/> <element ref = "Hawk:IPAddress"/> <element ref = "Hawk:OsArch"/> <element ref = "Hawk:OsName"/> <element ref = "Hawk:OsVersion"/> <element ref = "Hawk:RuleBaseEngineState"/> <element ref = "Hawk:StartYear"/> <element ref = "Hawk:StartMonth"/> <element ref = "Hawk:StartDate"/> <element ref = "Hawk:StartHour"/> <element ref = "Hawk:StartMin"/> <element ref = "Hawk:StartSec"/> <element name = "MicroAgents"> <complexType> <sequence> <element name = "MicroAgent" type = "string" maxOccurs = "unbounded"/> </sequence> </complexType> </element> <element name = "RuleBases"> <complexType> <sequence> <element name = "RuleBase" type = "string" maxOccurs = "unbounded"/> </sequence> </complexType> </element>


</choice> </complexType> </element> <element name = "AgentName" type = "string"/> <element name = "DnsName" type = "string"/> <element name = "HawkDomain" type = "string"/> <element name = "OsArch" type = "string"/> <element name = "OsName" type = "string"/> <element name = "OsVersion" type = "string"/> <element name = "AgentMajorVersion" type = "integer"/> <element name = "AgentMinorVersion" type = "integer"/> <element name = "AgentUpdateVersion" type = "integer"/> <element name = "AgentCluster" type = "string"/> <element name = "IPAddress" type = "string"/> <element name = "RuleBaseEngineState"> <simpleType> <restriction base = "integer"> <enumeration value = "1"/> <enumeration value = "2"/> <enumeration value = "3"/> <enumeration value = "4"/> <enumeration value = "5"/> <maxInclusive value = "5"/> <minInclusive value = "1"/> <totalDigits value = "1"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "StartYear" type = "integer"/> <element name = "StartMonth"> <simpleType> <restriction base = "integer"> <enumeration value = "1"/> <enumeration value = "12"/> <enumeration value = "2"/> <enumeration value = "3"/> <enumeration value = "4"/> <enumeration value = "5"/> <enumeration value = "6"/> <enumeration value = "7"/> <enumeration value = "8"/> <enumeration value = "9"/> <enumeration value = "10"/> <enumeration value = "11"/> <maxInclusive value = "12"/> <minInclusive value = "1"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "StartDate"> <simpleType> <restriction base = "integer"> <maxInclusive value = "31"/> <minInclusive value = "1"/>


Agents.xsd | 87

<totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "StartHour"> <simpleType> <restriction base = "integer"> <maxInclusive value = "24"/> <minInclusive value = "0"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "StartMin"> <simpleType> <list> <simpleType> <restriction base = "integer"> <maxInclusive value = "59"/> <minInclusive value = "0"/> <maxLength value = "2"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </list> </simpleType> </element> <element name = "StartSec"> <simpleType> <restriction base = "integer"> <maxInclusive value = "59"/> <minInclusive value = "0"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <simpleType name = "MicroAgent"> <restriction base = "string"/> </simpleType> <simpleType name = "RuleBase"> <restriction base = "string"/> </simpleType></schema>


Alerts.xsd

This is the schema definition for the Alerts URL. It is located in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/xsd directory.

<?xml version = "1.0" encoding = "UTF-8"?><schema xmlns = "http://www.w3.org/2001/XMLSchema" targetNamespace = "http://www.tibco.com/TIBCOHawk" xmlns:Hawk = "http://www.tibco.com/TIBCOHawk" xmlns:xsd = "http://www.w3.org/2001/XMLSchema" elementFormDefault = "qualified"> <element name = "Alerts"> <complexType> <sequence> <element name = "Alert" minOccurs = "0" maxOccurs = "unbounded"> <complexType> <sequence> <element name = "Agent"> <simpleType> <restriction base = "string"> <maxLength value = "8"/> <length value = "8"/> <minLength value = "1"/> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "HawkDomain"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "Dns"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "State"> <simpleType> <restriction base = "integer"> <enumeration value = "1"/> <enumeration value = "2"/> <enumeration value = "3"/> <enumeration value = "4"/> <totalDigits value = "1"/> <fractionDigits value = "0"/> </restriction> </simpleType>

Alerts.xsd | 89

</element> <element name = "Text"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "RuleBaseName"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "Rule"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "Test"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "DataSource"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "DataIndex"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "Action"> <simpleType> <restriction base = "string"> <whiteSpace value = "preserve"/> </restriction> </simpleType> </element> <element name = "AlertDate"> <simpleType> <restriction base = "integer"> <maxInclusive value = "31"/> <minInclusive value = "1"/> <totalDigits value = "2"/> <fractionDigits value = "0"/>



</restriction> </simpleType> </element> <element name = "AlertHour"> <simpleType> <restriction base = "integer"> <maxInclusive value = "23"/> <minInclusive value = "0"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "AlertMin"> <simpleType> <restriction base = "integer"> <maxInclusive value = "59"/> <minInclusive value = "0"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "AlertMonth"> <simpleType> <restriction base = "integer"> <maxInclusive value = "12"/> <minInclusive value = "1"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "AlerttSec"> <simpleType> <restriction base = "integer"> <maxInclusive value = "59"/> <minInclusive value = "0"/> <totalDigits value = "2"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "AlertYear"> <simpleType> <restriction base = "integer"> <totalDigits value = "4"/> <fractionDigits value = "0"/> </restriction> </simpleType> </element> <element name = "AlertId"> <simpleType> <restriction base = "integer"> <minInclusive value = "0"/> <fractionDigits value = "0"/> </restriction>


Alerts.xsd | 91

</simpleType> </element> </sequence> </complexType> </element> </sequence> </complexType> </element></schema>


MicroAgents.xsd

This is the schema definition for the MicroAgents URL. It is located in the HAWK_HOME/webconsole/tomcat/webapps/http/xsl/http/xsd directory.

<?xml version = "1.0" encoding = "UTF-8"?><schema xmlns = "http://www.w3.org/2001/XMLSchema" targetNamespace = "http://www.tibco.com/TIBCOHawk" xmlns:Hawk = "http://www.tibco.com/TIBCOHawk" xmlns:xsd = "http://www.w3.org/2001/XMLSchema" elementFormDefault = "qualified"> <element name = "AllMicroAgents"> <complexType> <sequence> <element name = "MicroAgents" maxOccurs = "unbounded"> <complexType> <sequence> <element name = "MicroAgent" maxOccurs = "unbounded"> <complexType> <sequence> <element name = "Name" type = "string"/> <element name = "Agent" type = "string"/> <element name = "DisplayName" type = "string"/> <element name = "Instance" type = "integer"/> <element name = "Service" type = "boolean"/> <element name = "Checksum" type = "float"/> <element name = "Methods"> <complexType> <sequence> <element name = "Method" maxOccurs = "unbounded"> <complexType> <sequence> <element name = "Name" type = "string"/> <element name = "Description" type = "string"/> <element name = "ResponseTime" type = "string"/> <element name = "Async" type = "string"/> <element name = "Impact" type = "string"/> <element name = "OpenMethod" type = "string"/> <element name = "Returns"> <complexType> <sequence> <element name = "Return" minOccurs = "0"> <complexType> <sequence> <element name = "Name" type = "string" maxOccurs = "unbounded"/> <element name = "Type" type = "string" maxOccurs = "unbounded"/> <element name = "Indices" minOccurs = "0"> <complexType> <sequence>

MicroAgents.xsd | 93

<element name = "Index" type = "string" minOccurs = "0"/> </sequence> </complexType> </element> <element name = "Description" type = "string" minOccurs = "0"/> </sequence> </complexType> </element> </sequence> </complexType> </element> <element name = "Arguments"> <complexType> <sequence> <element name = "Argument" minOccurs = "0"> <complexType> <sequence> <element name = "Name" type = "string" maxOccurs = "unbounded"/> <element name = "Type" type = "string" maxOccurs = "unbounded"/> <element name = "ValChoices" minOccurs = "0"> <complexType> <sequence> <element name = "ValChoice" type = "string" maxOccurs = "unbounded"/> </sequence> </complexType> </element> <element name = "LegalValChoices" minOccurs = "0"> <complexType> <sequence> <element name = "LegalValChoice" type = "string" maxOccurs = "unbounded"/> </sequence> </complexType> </element> <element name = "Description" type = "string" minOccurs = "0"/> </sequence> </complexType> </element> </sequence> </complexType> </element> </sequence> </complexType> </element> </sequence> </complexType> </element> </sequence> </complexType>



</element> </sequence> </complexType> </element> </sequence> </complexType> </element></schema>


| 95

Index

A

Additional Parameters 23AddRoot.xsl 37Agent Status 51AgentAlert.xsl 34Agents URL 24Agents URL Sample Output 24Agents, Alerts, and Microagents URLs 7Agents.xsd 85AgentState.xsl 33Alert Details 53Alert State Colors and Conditions 46Alert View 52Alerts URL 26Alerts URL Sample Output 26Alerts.xsd 88Alerts.xsl 37Applying a Cascading Stylesheet 41Architecture 13Authentication 61Authorization 64

B

Back and Return 43Basic Authentication 61

C

Can Be Applied To33, 34, 35, 35, 36, 36, 37, 37, 37, 38

Cascading Stylesheets 8, 45changes from the previous release viiiCluster View 50

ClusterView.xsl 35Constructing the Relative URL 41customer support xiiiCustomizing the Content, Look and Feel of XML

Data 6Customizing the HTML Application 45

D

Daemon parameter 18Date and Time Updated 45Default Alert Colors for Sample HTML

Application 46Domain View 49

E

Enterprise View 48Example 27, 35, 36, 36, 37Example 1 29, 31, 34, 34Example 2 29, 31, 34, 35Example 3 29, 31Example 4 31Example 5 32Examples 25, 29, 31Extended Architecture for Generating HTML

Interface 14

G

Generating HTML Pages from the XML Stream Using JSTL in JSP 40

getReleaseVersion 72


96 | Index

getReleaseVersion, method 72getTraceLevel 68getTraceLevel, method 68getTraceParameters 70getTraceParameters, method 70

I

Ident.xsl 37Implementing Own Java Security Class 65Importing the Tag Libraries 40Importing XML Content 41Introduction 2Invoke URL 7, 30Invoke URL Sample Output 30Invoking Relative URLs from the Index Page 22Invoking the Relative URLs 22

J

JSP/JSTL Files 8JSPs 45JSTL 40

L

Location of Files for Parsing XML Data into HTML (Cont’d) 45

M

Method Details 55Method Results 56Microagent View 54MicroAgents URL 28MicroAgents URL Sample Output 28MicroAgents.xsd 92

Missing dll Error 64Multiple TIBCO Hawk Domain Support 2

N

Navigation 43Network parameter 18Nnames.xsl 36

O

onUnsolicitedMsg 73onUnsolicitedMsg, method 73Optional Parameter

34Optional Parameters 24, 26, 29, 30Order of Parameters 23

P

Parsing the XML 41

Q

Qualified Names (QNames) 11

R

Realms 63Refresh Interval 45Relative URL Overview 22Required Parameter

34, 35, 35, 36Required Parameters 28, 30

33, 37


Index | 97

Result.xsl 38Retrieving the TIBCO Hawk Agent Data 41RuleBaseAlert.xsl 35RuleBaseListXml.xsl 36

S

Sample Files 75Sample HTML Interface Introduction 43Schema Definitions 7Screens in the Sample HTML Application 43Security Overview 60Service parameter 18, 18setTraceLevel 69setTraceLevel, method 69setTraceParameters 71setTraceParameters, method 71Starting the HTML Interface 47support, contacting xiii

T

technical support xiiiTIBCO_HOME xiTIBHawkXml Microagent Methods 67

U

Understanding the Highest Alert State 44Users and Roles 61Using Parameters in Relative URLs 22

W

web.xml 76

X

XML and HTML Interfaces 5XML Namespaces 10XSLT/XPATH Stylesheets 8, 33


tibco hawk™ http adapter - tibco product … hawk concepts guide |vii preface tibco hawk http...

Documents