TIBCO PageBus Developer,Aos Guide › pub › pagebus › 2.0.0-october... · programmatic interfaces, and best practices that help you successfully build composite rich internet

TIBCO PageBus™

Developer’s GuideSoftware Release 2.0October 2009

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 LICENSE.PDF) 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.TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO General Interface, TIBCO General Interface Framework, TIBCO General Interface Builder, TIBCO PortalBuilder, TIBCO PageBus, and TIBCO Ajax Message Service are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. 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.TXT 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 © 2007-2009 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 PageBus Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

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

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Support for the OpenAjax Hub 2.0 Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Additional TIBCO PageBus Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3TIBCO PageBus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3TIBCO PageBus Secure Mash-ups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5TIBCO PageBus Event Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

The Simple PageBus API and the Managed Hub API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Using the Simple PageBus API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Using the Managed Hub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Events: Topics and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Topic Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Valid and Invalid Topic Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Best Practices for Topic Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Best Practices for Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 2 The Simple PageBus API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22The PageBus Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

PageBus.publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

PageBus.subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

PageBus.unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

PageBus.query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

PageBus.store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

PageBus Subcribe onData Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

TIBCO PageBus Developer’s Guide

iv | Contents

PageBus.version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 3 The OpenAjax Managed Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Managed Hub Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Managed Hub Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Managed Hub Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Types of Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Loading the PageBus JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Sample Source Code: Manager Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Sample Source Code: Inline Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4 Managed Hub API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

The OpenAjax Hub 2.0 Specification Managed Hub APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

JSDoc Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Introduction the Managed Hub APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

OpenAjax.hub.Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

OpenAjax.hub.SecurityAlert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Common callback functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

OpenAjax.hub.Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

OpenAjax.hub.ManagedHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

OpenAjax.hub.Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

OpenAjax.hub.IframeContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

OpenAjax.hub.InlineContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

OpenAjax.hub.HubClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

OpenAjax.hub.IframeHubClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

OpenAjax.hub.InlineHubClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Chapter 5 PageBus HubPolicy Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

PageBus HubPolicy Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Access Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Granting and Revoking Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Enforcing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Using PageBus HubPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Chapter 6 PageBus HubPolicy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

PageBus.policy.Ops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

PageBus.policy.HubPolicy.grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103


Contents | v

PageBus.policy.HubPolicy.revoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

PageBus.policy.HubPolicy.revokeAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

PageBus.policy.HubPolicy.isAllowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

PageBus.policy.HubPolicy.listAllowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

PageBus.policy.HubPolicy.onPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

PageBus.policy.HubPolicy.onSubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 7 The PageBus Event Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112How Cache Entries Are Managed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Cache-Enabled Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Storing Data in the Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Querying the Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Enabling Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Disabling Caching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Cache Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

PageBus Event Cache Function Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

The PageBus Sub-Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Hub.pagebus.query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Hub.pagebus.store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 8 Best Practices and FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Callback Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122No Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Synchronous or Asynchronous?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Return Quickly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Event Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Security Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Frame Phishing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Load Timeout and ForgedMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Disconnect and Reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Removing a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Configuration Driven Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Timeouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Browser-specific behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131


vi | Contents

Chapter 9 Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134


| vii

Preface

This manual provides an introduction to TIBCO PageBus™, a publish/subscribe message delivery hub for mash-ups and rich internet applications. PageBus simplifies the development and extension of web applications composed of Ajax components, including rich portlets. This manual explains the PageBus concepts, programmatic interfaces, and best practices that help you successfully build composite rich internet applications (RIAs).

Topics

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

• Related Documentation, page ix

• Typographical Conventions, page x

• How to Contact TIBCO Support, page xii


viii | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

The major changes from the previous release of this guide are the descriptions of the following PageBus 2.0 features:

Secure Mash-ups

TIBCO PageBus allows the construction of secure mash-ups even when some of the components are from external or third-party systems. These "untrusted components" can be isolated in secure sandboxes but still communicate with other parts of the mash-up via the PageBus hub.

PageBus HubPolicy

The PageBus HubPolicy is a security manager that allows applications to restrict the information to which each component has access over TIBCO PageBus. Applications can dynamically grant and revoke privileges.

PageBus Event Cache

TIBCO PageBus provides a built-in event cache that allows subscribers to receive events that were published before they were created. The cache can also be used to manage properties that are shared between components. Access to cached values is governed by the PageBus HubPolicy security manager.

OpenAjax Hub 2.0

TIBCO PageBus contains a complete implementation of the OpenAjax Hub 2.0 specification. This implementation includes both Iframe Container (for isolation) and Inline Container (for trusted components).


Preface | ix

Related Documentation

You may find the OpenAjax Hub 2.0 Specification useful. The specification can be found online at this location:

http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification

TIBCO PageBus DocumentationThe following documents form the PageBus documentation set:

• TIBCO PageBus Developer’s Guide Read this manual for instructions on using the product to....

• TIBCO PageBus 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, if any.


http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification

x | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

ENV_HOME

Many TIBCO products must be installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco.

Other TIBCO products are installed into an installation environment. Incompatible products and multiple instances of the same product are installed into different installation environments. The directory into which such products are installed is referenced in documentation as ENV_HOME. The value of ENV_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco.

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.

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


Preface | xi

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


xii | How to Contact TIBCO Support

How to Contact TIBCO Support

For 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.tibco.com/services/support

https://support.tibco.com

| 1

Chapter 1 Introduction

This chapter gives an introductory description of TIBCO PageBus, and explains how PageBus enables enables rich web components to interact securely with each other.

Topics

• Introduction, page 2

• The Simple PageBus API and the Managed Hub API, page 10

• Sample Code, page 15

• Events: Topics and Messages, page 16


2 | Chapter 1 Introduction

Introduction

In order to achieve greater flexibility and promote broader use of available business assets, application developers are increasingly taking advantage of service oriented architectures (SOA). This trend is contributing to the rapid growth of “enterprise mash-ups”—composite Ajax applications that interact with disparate web services across the enterprise.

In modern service oriented architectures, the server side is characterized by heterogeneous components that interact using well-defined, coarse-grained service interfaces. These characteristics are uniformly recognized as promoting reuse, loose coupling, and discoverability, essential qualities in an era of rapid change. On the client side, however, many enterprise web applications are monolithic and are built from scratch each time, with either too much functionality or too little functionality to be repurposed for new tasks.

Simultaneously, enterprises are increasingly adopting Ajax component-based approaches as a way to build rich enterprise applications. An Ajax component strategy separates UI functionality into coarse-grained modules (such as “web widgets” and “data feeds”) that can be composed by application developers or end users to create sophisticated user interfaces. Ajax techniques allow these components to access disparate web services.

These two trends are highly complimentary. Web applications can be constructed from different rich Ajax components, and these components can interact with each other when assembled on the page—an ideal strategy for creating enterprise mash-ups. When dashboards and portals are used, business users can even assemble and personalize application components on their own pages, creating mash-ups dynamically.

However, not all components can be trusted with the same information and access, and for security reasons, components that are trusted with a piece of information must be isolated from those that are not.

TIBCO PageBus provides a standards-based way to build secure mash-ups in which components can be isolated in secure sandboxes and interact only via publish-subscribe events. The events pass through the mash-up application’s security manager, which allows or denies each subscribe or publish request.

By creating components that interact with each other only via these well-defined, coarse-grained PageBus events, developers are able to deliver the same kind of reusability, evolvability, loose coupling and discoverability that characterize the services of the SOA. TIBCO PageBus is the SOA on the Glass™.


Introduction | 3

Support for the OpenAjax Hub 2.0 SpecificationTIBCO PageBus fully supports the OpenAjax Hub 2.0 standard. It includes a complete implementation of the OpenAjax Hub specification, including both the simpler Unmanaged Hub and the more sophisticated Managed Hub (for secure mash-ups).

Additional TIBCO PageBus FeaturesTIBCO PageBus also provides additional off-the-shelf functionality in a manner that is both compatible with the specification and easy to use:

• TIBCO PageBus Security Manager: Includes an off-the-shelf security manager, called PageBus HubPolicy, that lets mash-ups and components control what information is shared

• TIBCO PageBus Event Cache (previously called PageBus Repository): allows components to share state values securely across sandboxes and allows components to interact even if they do not exist at the same moment in time.

• Simple PageBus API: PageBus.publish(), etc.

Messages published using the Simple PageBus API can be consumed by subscribers that use the lower-level OpenAJax Hub API, and vice versa.

TIBCO PageBusTIBCO PageBus is a pure JavaScript, publish-subscribe message delivery hub in which publishers send (or publish), events and subscribers subscribe to these events. Events can be defined by the application; they usually represent business or application events such as a user’s selection of a customer or a user’s creation of a new calendar appointment.

Events are identified by topic strings such as:

org.pagebus.example.Location

and contain data whose structure and meaning can be defined by the application. The following lines show an example of an event body:

{ eventClass: "org.pagebus.example.Location" latitude: 45.000, longitude: -107.110, name: "Buried Treasure"}



An unlimited number of subscribers may subscribe to each topic; an unlimited number of publishers may publish event messages on the topic. Subscribers that need to subscribe to many similar topics at a time can subscribe to wildcard topics, such as "com.example.foo.*".

Publishers and subscribers are “anonymous”; they do not need to register with each other and need not be aware of each other’s existence.

Figure 1 shows the logical representation of PageBus, publishers, and subscribers.

Figure 1 PageBus, Publishers, and Subscribers

Figure 2 illustrates PageBus publish-subscribe messaging between three portlets in an enterprise portal. In this figure, the upper left portlet contains a list from which the user chooses one of TIBCO’s worldwide offices. The other two portlets then display information related to the selected office. When a user clicks a city in the TIBCO Office Selector portlet, that portlet publishes a message on the topic eg.geo.Location.onSelect. The other two portlets, Currency Cross and Google Map Example, are subscribers to eg.geo.Location.onSelect. Whenever these subscribers receive a message, they perform whatever action is appropriate to their function. As the figure below shows, Currency Cross displays a graph of recent exchange rates for the local currency, while Google Map Example maps the location of the selected office.


Introduction | 5

Figure 2 Publish-subscribe messaging between portlets with TIBCO PageBus

TIBCO PageBus Secure Mash-upsTIBCO PageBus also includes an OpenAjax Managed Hub implementation that allows a mash-up application to isolate untrusted components in secure sandboxes, so that the only way these components can communicate with the mash-up and the other components is by using the PageBus publish-subscribe hub. When the Managed Hub is used, the off-the-shelf TIBCO PageBus Security Manager (PageBus HubPolicy) evaluates each publish and subscribe request.

In the Managed Hub case, the mash-up application creates a Managed Hub instance and a set of Container objects – one Container per component. Each Container may be either an Iframe Container, in which case the component is isolated in a secure sandbox, or an Inline Container, in which case the component is embedded directly in the page and is not isolated.

When a component is embedded in an Iframe Container, the mash-up page contains an iframe with a different origin (if a main page has the origin http://mashup.foo.bar.com, then a sandbox iframe might be located at http://container1.foo.bar.com). The application loads each untrusted component within its own sandbox iframe.



As long as an iframe has a different origin than the main page and the other sandboxes, the web browser’s native security features[1] prevent JavaScript within the sandbox from accessing JavaScript or DOM within the main page and other sandboxes. Thus, PageBus uses the browser itself to enforce isolation.

Figure 3 shows how sandboxes isolate components, allowing them to communicate only via the TIBCO PageBus hub, which enforces the security policies specified by the mash-up application.

Figure 3 Isolating components within secure sandboxes

Because related components typically need to access the same web services, cookies, etc., the Iframe Containers of components that access the same services typically share the same origin. To ensure isolation, this origin must be different from those used by the sandbox iframes of other, unrelated components.

PageBus Hub Policy

Because the web browser’s native security model is based on origin, the off-the-shelf PageBus HubPolicy Security Manager is likewise based on origin.

The PageBus HubPolicy security manager allows the application to specify the set of topics on which each origin is permitted to publish and/or subscribe. All components associated with an origin share that origin’s permissions.

For example, if a mash-up application grants to the origin http://c0.foo.bar.com the right to publish on the topic org.example.geo.location.select, then all Iframe containers whose origin is http://c0.foo.bar.com will be permitted to select locations by publishing on this topic. If the mash-up application grants to the origin


Introduction | 7

http://mashup.foo.bar.com the right to subscribe to org.example.geo.location.select, then components embedded within the mash-up page (using Inline Containers rather than Iframe Containers) will be permitted to subscribe to that topic.

An application that uses the PageBus HubPolicy security manager grants permissions to origins based on whether these origins are trusted to access specific types of information (represented by the topics on which this information is published). The resulting permission model is very simple and easy to manage, which is a very important part of ensuring an appropriate level of security.

The Security Manager (PageBus HubPolicy) allows mash-up applications to dynamically grant and revoke permissions and may issue a query at any time. It supports permission grants to wildcard topics. And it allows applications to add their own custom security policies and hooks (for example, wiring hooks) on top of the built-in security manager.

Untrusted Mash-ups

TIBCO PageBus also allows a component in a Container to refuse to send or receive certain events, depending on the origin of the mash-up page that owns the Container. This feature allows an embeddable component that is packaged as an iframe to avoid exchanging sensitive information with untrustworthy mash-ups.

This functionality is very useful in portals, dashboards and other general-purpose applications, in which a component such as a rich portlet may be reused in a wide variety of contexts, some of which may be less trustworthy than others.

Chapter 5, PageBus HubPolicy Overview, on page 91 and Chapter 6, PageBus HubPolicy Reference, on page 101 describe the PageBus HubPolicy security manager in more detail.

TIBCO PageBus Event CacheThere are times when the ordinary publish-subscribe pattern is insufficient to meet application requirements.

For example, in the application shown in Figure 4, the upper left-hand pane contains a list of locations and the right-hand pane contains a map. The left-hand component uses PageBus to publish an event, telling the map component to add a marker at the currently selected location. If the list of locations publishes its currently selected value before the map portlet subscribes, the mash-up will not initialize properly



Figure 4 A properly initialized widget connecting a list of locations and a map

When the page is first loaded, the two components initialize themselves simultaneously. When the list first loads, it publishes a default location that the map is supposed to display. Unfortunately, the list might initialize more quickly than the map, and may publish its event before the map subscribes. The map will never receive the event and will not display the proper default location.

This example highlights a more general challenge: how to implement an application in which a publisher may publish before the subscriber is ready to receive.

TIBCO PageBus solves this problem by providing an event cache for each hub instance. The event cache stores copies of published events and can deliver these events to subscribers that are created later. Components can also query the cache to retrieve the value most recently published on a specified topic.

Creating and Managing Caches

Not all topics are cached. To enable caching on a topic, either the mash-up or a component creates a cache-enabled subscription by calling Hub.subscribe with a particular type of subscriberData parameter. Caching remains enabled on a topic as long as there is at least one cache-enabled subscription for that topic. After the last cache-enabled subscription for a topic is destroyed, the topic’s cache is automatically destroyed.


Introduction | 9

A mash-up application may create cache-enabled subscriptions on a (possibly configured) set of topics, thus cache enabling these topics. It may then initialize a set of components that publish and subscribe to these topics. Even if a publisher publishes an event before the components' subscribers initialize, the event is stored in the cache, which delivers it to the eventual subscribers.

A cache-enabled subscription to a wildcard topic enables caching on all topics that match the wildcard.

Caching is transparent to publishers; publishers do not need to do anything special when caching has been enabled on a given topic.

A cache-enabled topic is a topic for which caching is enabled within a hub instance.

The PageBus Event Cache can be used with both the Managed Hub and the Unmanaged Hub. When the Managed Hub is used, all access to the cache is controlled by the PageBus HubPolicy security manager.

Other Uses

The PageBus Event Cache helps to resolve the “late subscriber” issue described at the beginning of this section. It also makes it easy for components and frameworks to implement a mechanism by which components and mash-ups can share property values. When used with the Managed Hub, this mechanism leverages the PageBus HubPolicy security manager to prevent untrusted components from accessing sensitive properties.

Chapter 7, The PageBus Event Cache, on page 111 describes the PageBus Event Cache in more detail.



The Simple PageBus API and the Managed Hub API

TIBCO PageBus makes it easy to build modular applications by composing user interface components such as widgets and data bridges. Sometimes all of the components are developed by the organization’s own IT staff and are fully trusted. In other cases, some of the components, such as externally provided web widgets, are not trusted with access to some of the information and services used by the mash-up as a whole.

For the trusted case, primarily associated with programmer-built mash-ups and similar custom applications, TIBCO PageBus provides a Simple PageBus API that leverages the OpenAjax specified Unmanaged Hub. This single-page implementation is very easy to use and is lightweight and fast, but does not provide containers to isolate untrusted components or a security manager to manage traffic on the hub.

For the untrusted case, primarily associated with portals, personalized dashboards and other platforms that allow end users to compose widgets into mash-ups, TIBCO PageBus provides an implementation of the OpenAjax Managed Hub specification. This provides sandboxes and a security manager.

The Managed Hub and the Unmanaged Hub both provide pure JavaScript frameworks that deliver publish-subscribe messaging based on topics and the PageBus event cache. Both implement the complete OpenAjax 2.0 specification.

Table 2 compares the Unmanaged Hub with the Managed Hub.

Table 2 Comparison of the Unmanaged Hub with the Managed Hub

Features & Characteristics

Simple PageBus API and Unmanaged Hub Managed Hub

Publish-Subscribe API based on topics

Yes Yes

PageBus event cache Yes Yes

JavaScript code size Small Larger

Containers can isolate components

No Yes

Security manager No Yes


The Simple PageBus API and the Managed Hub API | 11

Using the Simple PageBus APIThe Simple PageBus API is a singleton PageBus object that permits components to publish, subscribe and query the event cache. A PageBus mediated interaction involves the following steps:

Figure 5 Initialization and use of Simple PageBus API

PageBus Event Cache

The Simple PageBus API also supports the PageBus Event Cache.

Number of hub instances

Exactly one singleton PageBus hub instance

Application can create any number of Managed Hub instances (e.g., complex components can use private hubs for internal communication).

Integrates components with different origins

No Yes

Table 2 Comparison of the Unmanaged Hub with the Managed Hub

Features & Characteristics

Simple PageBus API and Unmanaged Hub Managed Hub



Figure 6 Simple PageBus API with PageBus Event Cache

Unmanaged Hub APIs

TIBCO PageBus also implements the OpenAjax Unmanaged Hub API. The PageBus functions call this interface, so the PageBus Simple API and OpenAjax Unmanaged Hub interface are seamlessly interoperable. Events published via the OpenAjax Unmanaged Hub API can be received by subscribing via the Simple PageBus API, and vice versa.

Using the Managed HubWhen some components used in a mash-up, such as externally provided web widgets, are not trusted to access some of the information and services used by the mash-up as a whole, the Managed Hub enables the mash-up to isolate these untrusted components in secure sandboxes and restrict their access to information flows via a security manager (PageBus HubPolicy).

In the Managed Hub case, the mash-up application creates a Managed Hub instance and a set of Container objects – one Container per component. Each Container may be either an Iframe Container, in which case the component is isolated in a secure sandbox, or an Inline Container, in which case the component is embedded directly in the page and is not isolated.

PageBus implements these mechanisms in a manner that comforms to the OpenAjax Hub 2.0 specification. In addition, applications can specify their own custom security manager callback functions either on top of or in place of the off-the-shelf PageBus feature.


The Simple PageBus API and the Managed Hub API | 13

Figure 7 shows how a mash-up application instantiates a ManagedHub and some components, and how these components communicate with each other via the hub.

Figure 7 Use of a Managed Hub

PageBus Event Cache

Applications that use the Managed Hub can take advantage of the PageBus Event Cache. Components and mash-up applications can use the cache to share state or synchronize property values, even if the components do not exist at the same moment in time.

The Event Cache provides a master-slave replication model, where the cache owned by the Managed Hub is the master and the other cache instances are the slaves.

While both components and mash-up applications can create and use caches, a cache created by the mash-up application and shared by the components is the most useful. Figure 8 shows how this is done.



Figure 8 Using ManagedHub with PageBus Event Cache

A mash-up application can create an event cache for a topic by calling the subscribe function with certain parameter values. This creates a cache-enabled subscription and a master cache within the Managed Hub.

A component can create an event cache for a topic by calling the subscribe function with certain parameter values. This creates a cache-enabled subscription, a master cache within the Managed Hub and a local cache within the local HubClient.

Once created, a topic remains cache-enabled as long as at least one cache-enabled subscription is using that cache. When the last subscriber is destroyed, the cache is automatically cleaned up.

Caching is an optional feature. Subscribers that enable caching receive cached events from the cache; subscribers that do not enable caching do not. Once the delivery of the cached events has completed, cache-enabled subscriptions behave exactly like ordinary subscriptions.


Sample Code | 15

Sample Code

Samples for TIBCO PageBus are provided in the samples directory of the PageBus directory.



Events: Topics and Messages

The Simple PageBus API and the Managed Hub framework use exactly the same event mechanism.

TIBCO PageBus events consist of the following:

• A topic name, such as com.example.calendar.event.created, which might announce that a calendar event has been created.

• A message (the event payload), which contains arbitrary application-level information. This is typically a JavaScript object, for example:

{ date: "2009/09/15",time: "07:00:00 PM",tz: "+0",name: "Mary's birthday party",location: "The Flying Fish Restaurant"

}

Topic NamesA topic name, or topic, is a string consisting of one or more tokens separated by "." (0x2E) characters. For example:

• com.example.customer.onSelect

• org.pagebus.log.info

A topic may optionally contain wildcards. There are two kinds of wildcards:

• “*” (0x2A) matches exactly one whole token, regardless of its value. It can appear anywhere in the topic, and there can be multiple “*” wildcard tokens per topic.

• “**” matches one or more entire tokens. It may only appear at the end of the topic.

Single-Token Wildcard (“*”)

A * wildcard matches a single-token. For example, a.*.c matches both a.b.c and a.xxxxxxxxxxxxxxxxx.c. It does not, however, match a.b.b.b.c or a.c.

A * wildcard may appear at any position in a topic (including the first token and the last token). There may be multiple * wildcard tokens per topic. The topic a.*.b.*.cc.* matches a.x.b.6.cc.&& and a.foo.b.entrepreneur.cc.dddd.


Events: Topics and Messages | 17

Suffix Wildcard (“**”)

A ** wildcard matches one or more tokens. For example, a.b.** matches a.b, a.b.c and a.b.77777.88888.99999.10.11.12.13.14.=====. The topic ** matches all legal topics.

If a “**” appears in a topic, it MUST appear as the final token in the topic.

Valid and Invalid Topic NamesThe following are examples of valid topics:

Valid Topic Explanation

com.tibco.geo.location.select

Has 5 tokens: com, tibco, geo, location, and select

TIBCO Has one token: TIBCO

a Has one token: a

T7.f3.$r.^ttx.# Has the tokens T7, f3, $r, ^ttx, and #

* Wildcard topic matching any 1-token topic

** Wildcard topic matching any topic

a.*.c Wildcard topic matching any 3-token topic whose first token is a and whose third token is c

a.b.c.d.** Wildcard topic matching any topic with 4 or more tokens, where the topic begins with a.b.c.d.

Com.example.*.foo.** Wildcard topic matching any topic with 4 or more tokens, where the first two tokens are Com.example and the fourth token is foo.

*.*.** Wildcard topic matching any topic with 3 or more tokens.



The following are examples of invalid “topics”:

Best Practices for Topic Names

Use Reverse DNS Topic Names

Each topic name should follow a reverse DNS pattern, where the prefix for the event’s topic is the name of the organization that defines an event type.

This technique ensures that different component developers do not create events whose semantics or message structure differ, but which have the same topic.

Invalid Topic Explanation

T.A*.F When * appears in a topic, it must appear as a whole token.

X.*B.X When * appears in a topic, it must appear as a whole token.

H*W.X When * appears in a topic, it must appear as a whole token.

**.a.b ** must appear only at the end of the topic.

a.**.b ** must appear only at the end of the topic.

. There must be at least one token per topic. This topic has no tokens.

.a.b.c A token can never be empty. In this example, the first token is empty.

a.b.c. A token can never be empty. In this example, the last token is empty.

... A token can never be empty. All four tokens in this example are empty.

a..c A token can never be empty. In this example, the second token is empty.


Events: Topics and Messages | 19

_pagebus

Topics beginning with _pagebus are reserved for internal use by TIBCO PageBus.

Localization and Characters

Any Unicode character except for “*” and “.” is theoretically permitted to appear in a topic. However, it is best to avoid characters that confuse readers or may cause issues in editors. Quotation marks, spaces, control characters, and punctuation characters should be avoided if possible.

MessagesEvents contain payloads, called messages. As long as Iframe Containers and the Event Cache are not used, messages can theoretically contain any kind of data. However, Iframe Containers and the PageBus Event Cache both require that the message contain only data objects that can be serialized as JSON (see www.json.org). In practice, this means that messages should only contain the following types of data: null, Boolean, string, number, array and object. Functions and native web browser objects such as window should not be included.

Subscribers must always treat message objects and arrays as read-only values.

Best Practices for MessagesMessages should probably be objects rather than atomic values, and message objects should contain schema name fields that indicate the object type or class.


http://www.json.org



| 21

Chapter 2 The Simple PageBus API

The Simple PageBus API provides a fast, simple publish-subscribe engine. It does not implement containers or security. (If you need containers and secure mash-ups, consult the Managed Hub chapter.) The Simple PageBus API does support the PageBus Event Cache.

Topics

• Overview, page 22

• PageBus.publish, page 23

• PageBus.subscribe, page 25

• PageBus.unsubscribe, page 27

• PageBus.query, page 28

• PageBus.store, page 29

• PageBus Subcribe onData Callback, page 31

• PageBus.version, page 32


22 | Chapter 2 The Simple PageBus API

Overview

The Simple PageBus API provides a fast, simple publish-subscribe engine. It does not implement containers or security. It does support the PageBus Event Cache.

The Simple PageBus API includes the following functions:

The Simple PageBus API also includes the following data members:

The PageBus ObjectPageBus is a singleton object.

Table 3 Simple PageBus API functions

Function Comment

PageBus.publish Publish a message on a topic. If there is an event cache for this topic, a copy of the message will also be saved in the event cache.

PageBus.subscribe Subscribe to a topic. With certain parameters, also creates a cache for the specified topic.

PageBus.unsubscribe Cancel a subscription created by subscribe().

PageBus.query Query the cache for events matching the specified topic.

PageBus.store If there is a cache for the specified topic, publish to update it. Otherwise throw an exception so that the caller knows that the topic is not cache-enabled.

Table 4 Simple PageBus API data member

Data Member Comment

PageBus.version Constant.


PageBus.publish | 23

PageBus.publishFunction

Description The publish function publishes one message on a topic. The message is delivered to all current subscribers whose subscriptions match the topic.

If there are multiple subscribers, the order in which the message is delivered to the various subscribers is arbitrary.

If PageBus.publish is called twice, so that two messages are published in sequence, then subscribers will always receive the message that was published first before they receive the second message.

Returns Null

Parameters

Throws

Remarks When a publisher publishes on a topic for which an event cache exists, publish automatically makes a copy of the message value and stores the copy in the cache. This is a "deep copy,"meaning that all sub-objects and arrays contained within the value are copied. Message values must therefore be copyable. Message values must therefore consist of the following types:

• null

• Boolean (true, false)

• String

• Number

• Object (a JavaScript object such as { foo: 7, bar: { baz: [“x”, “y”] } } )

• Array

Name Type Description

topic string Topic name on which to publish the message. This must NOT be a wildcard topic.

message any (see below)

Message content. This data value SHOULD be serializable as JSON. If the event cache is used, this data value MUST be serializable as JSON.

OpenAjax.hub.BadParameters An invalid topic was specified. A topic may be invalid either because it is not a legal topic name (see Topic Names) or because it is a wildcard topic.



When caching is used, data values must NOT include functions, Date objects, web browser objects or other values that cannot be deep-copied. In general, even when there is no caching, we strongly recommend that only JSON-serializable message values be published.

All PageBus functions can be safely called from within PageBus callback functions.

When a Pagebus Callback Throws an Error

Subscription callbacks should not throw exceptions. If a subscription callback throws an Error, then if OpenAjax.hub.Debug is true, PageBus interrupts execution via the debugger JavaScript keyword. If OpenAjax.hub.Debug is false, then PageBus.publish ignores the error, other than generating a log message if a logging function is provided.

Removed or Changed since PageBus 1.2

PageBus.StackOverflow error Removed

PageBus.BadParameter error Replaced by OpenAjax.hub.BadParameters error

Handling when subscriber onData callback throws an Error

Previously, a message was published on a special topic. The new troubleshooting behavior mirrors what we have introduced into the Managed Hub.


PageBus.subscribe | 25

PageBus.subscribeFunction

Description The subscribe function creates a subscription to a topic name. When an event is published on a topic name that matches the specified topic, the subscriber's onData callback function is invoked.

If the subscription's topic name contains wildcards, then the subscriber will be notified via its onData callback function if the wildcard topic associated with the subscription matches the topic of the published event, even if the two topics are not identical. For example, if a subscriber subscribes to “a.b.*”, then it will be notified when someone publishes on the topic “a.b.c” or the topic “a.b.x”.

Returns String

This opaque string is the Subscription ID.

Parameters Name Type Description

topic string Topic name on which to subscribe. This MAY be a wildcard topic.

scope object If the value is non-null, the object specified here becomes the context of the callback function. In other words, when the JavaScript “this” keyword is used in the callback function, it will point to this object.

If the value is null, then the object window is used as the default context of the callback function.

onData function Callback function for PageBus to invoke when a message is published on the subscribed subject. See Subscription Callback for the required function signature.

This parameter must NOT be null.

subscriberData any User-defined. Null values are permitted. This is useful when the subscriber needs to access or update any data members when the callback function is invoked.

The value of the subscriberData parameter determines whether the subscriber is cache-enabled. See Remarks section below.



Throws

Remarks To cache-enable a subscription, specify a subscriberData parameter that is an object containing the following property:

PageBus: { cache: true }

Thus, if the value of the subscriberData parameter is

{ x: 1, y: “foo”, z: { w: 1 }, PageBus: {cache: true} }

then the subscriber will be cache-enabled.


OpenAjax.hub.BadParameters An illegal topic was specified (see Topic Names)

PageBus.BadName error Replaced by OpenAjax.hub.BadParameters error


filter parameter Removed. The OpenAjax Hub 2.0 specification removed the filter parameter.


PageBus.unsubscribe | 27

PageBus.unsubscribeFunction

Description The unsubscribe function cancels a subscription, using the Subscription ID returned by PageBus.subscribe as a handle to the subscription.

Returns null

Parameters

Throws

Remarks The unsubscribe function can be safely called from within PageBus callback functions.

If a cache-enabled subscription is unsubscribed, and that subscription is the last one using a particular event cache, then the event cache is automatically destroyed.



subscription string Subscription ID returned by PageBus.subscribe

OpenAjax.hub.BadParameters The parameter is not a valid subscription ID




PageBus.queryFunction

Description The query operation returns all event cache entries that match the specified topic name (which might be a wildcard topic).

The result of a non-wildcard query will contain 0-1 events, depending on whether there is a value in the cache for that topic. A query on a wildcard topic returns 0 or more events, one for each value in the cache whose topic matches the wildcard specified in the query.

Returns Array of Objects

Each object has the form { topic: topic, value: value }.

Parameters

Throws

Remarks Can be safely called from within a PageBus callback function or a repository query callback function.


The function signature has changed significantly since PageBus 1.2. All parameters other than topic have been dropped.


topic string Topic name. This MAY be a wildcard topic.

OpenAjax.hub.BadParameters An illegal topic was specified (see Topic Names).


PageBus.store | 29

PageBus.storeFunction

Description If the specified topic is cache-enabled, calls PageBus.publish to store the specified value and notify subscribers of the change. Otherwise, throws PageBus.cache.Error.NoCache exception.

Returns Null

Parameters

Throws

Remarks When a publisher publishes on a cache-enabled topic, publish automatically makes a copy of the message value and stores the copy in the cache. This is a "deep copy," meaning that if the value contains nested sub-objects or arrays, these too are copied.. Message values must therefore be copyable. Message values must therefore consist of the following types:

• null


• String

• Number

• Object (a JavaScript object, e.g., { foo: 7, bar: { baz: [“x”, “y”] } } )

• Array

Data values must NOT include functions, Date objects, web browser objects or other values that cannot be deep-copied or other values that are not included in the list of supported types.


topic string Topic name on which to publish the message. This must NOT be a wildcard topic.

message any (see below)

Message content. This data value MUST be serializable as JSON.

OpenAjax.hub.BadParameters The specified message is not JSON-serializable, or the topic name is invalid. A topic may be invalid either because it is not a legal topic name (see Topic Names) or because it is a wildcard topic.

PageBus.cache.Error.NoCache There is no cache for the specified topic.



This function can be safely called from within PageBus callback functions.


PageBus.BadName error Replaced by OpenAjax.hub.BadParameters error


props parameter with quiet property Removed. Use a security policy to prevent events from propagating.


PageBus Subcribe onData Callback | 31

PageBus Subcribe onData CallbackCallback Function

This section describes the signature of the onData callback function that must be passed into PageBus.subscribe().

Description The onData callback function that a caller provides to PageBus.subscribe processes each message that is delivered to the subscription. A function must be implemented with the parameters below and passed into PageBus.subscribe as the onData parameter. The function processes each message published on topics that match the topic specified in the PageBus.subscribe call.

Returns Null

Parameters

Remarks Callbacks should not throw exceptions. They should catch and handle their own exceptions. PageBus will silently swallow thrown exceptions unless debugging is enabled, in which case the debugger keyword is used to insert a breakpoint.

onData callback functions must not modify the message parameter, even if it is an object.

PageBus.subscribe, PageBus.unsubscribe, and PageBus.publish can be safely called from within the callback functions.

Message Sequence for Recursive Publish

PageBus enforces FIFO delivery of messages. If the delivery of a message results in the publication of a second message, all subscribers who receive both messages will receive the first message before they see the second one.

If a subscriber callback calls PageBus.publish recursively, TIBCO PageBus.publish ensures FIFO delivery of the messages.


topic string Topic name on which the message was pub-lished

message any Published message payload. Read-only

subscriberData any subscriberData parameter that was passed into PageBus.subscribe()



PageBus.versionConstant

Description This is a string constant that indicates the PageBus API version number. Its value is 2.0.0.


| 33

Chapter 3 The OpenAjax Managed Hub

This chapter explains how TIBCO PageBus implements the OpenAjax Managed Hub. The Managed Hub allows a mash-up application to isolate untrusted components in secure sandboxes, so that the only way these components can communicate with the mash-up and the other components is by using the PageBus publish-subscribe hub.

The Managed Hub implementation provided by TIBCO PageBus supports the PageBus Event Cache.

Topics



34 | Chapter 3 The OpenAjax Managed Hub

Overview

TIBCO PageBus includes an OpenAjax Managed Hub implementation that allows a mash-up application to isolate untrusted components in secure sandboxes, so that the only way these components can communicate with the mash-up and the other components is by using the PageBus publish-subscribe hub.

The mash-up application creates a Managed Hub instance and a set of Container objects – one Container per component. Each Container may be either an Iframe Container, in which case the component is isolated in a secure sandbox, or an Inline Container, in which case the component is embedded directly in the page and is not isolated.

When a component is embedded in an Iframe Container, the mash-up page contains an iframe with a different origin (if a main page has the origin http://mashup.foo.bar.com, then a sandbox iframe might be located at http://container1.foo.bar.com). The application then loads each untrusted component within its own sandbox iframe.

Managed Hub ElementsFigure 9 summarizes the modules that comprise the Managed Hub architecture. Light blue translucent arrows represent interactions via public APIs. Black arrows represent interactions that are private and are specific to a particular Container implementation. For example, each type of Container interacts with its associated HubClient using an implementation-specific mechanism such as HTML 5 postMessage, setting the fragment identifier within the iframe URL, or direct JavaScript function calls against a private interface.

Figure 9 Managed Hub Modules


Overview | 35

The Managed Hub architecture is composed of the following elements:

Table 5 Managed Hub Elements

Element Description

Manager Application Script running within application’s main HTML document

• Instantiates ManagedHub

• Creates a Container for each embedded component

• Sets component publish/subscribe privileges

OpenAjax.hub.ManagedHub

(One or more)

The hub (there is typically only one top-level Managed Hub per mash-up or application)

• Secure communication hub for components and Manager Application

PageBus.policy.HubPolicy

(Optional, one per ManagedHub)

The Manager Application can associate a PageBus HubPolicy security manager object with each ManagedHub.

• Allows Manager Application to control the topics to which each Container is allowed to publish and subscribe



OpenAjax.hub.Container

(One or more per ManagedHub)

Manager Application creates a Container for each component.

• Container encapsulates its component

• Container may isolate its component in a sandbox.

• A component interacts with the Managed Hub exclusively via its Container.

There are 2 types of built-in Containers:

• IframeContainer: Isolates the component in a secure sandbox consisting of an iframe with a different origin than that of the Manager Application’s page.

• InlineContainer: Places its client application into a HTML element (e.g. a DIV) within the Manager Application’s browser window. There is no isolation, so this type of Container is only used for trusted components. Faster than IframeContainer

OpenAjax.hub.HubClient

(One per Container)

When a Container loads and initializes a component, a HubClient object is created. Each type of Container has its own type of HubClient.

• Component uses HubClient to publish, subscribe and otherwise interact with the ManagedHub.


Element Description


Overview | 37

As the table indicates, there may be one or more ManagedHub object. In most cases, there is only one, but in some cases, there may be a need for several private hubs. For example, if a widget is itself a mash-up that includes several sub-components, it may contain a private Managed Hub instance that allows these sub-components to communicate privately with each other.

There can be many IframeContainers per ManagedHub. However, EXACTLY ONE IframeHubClient instance is instantiated by each IframeContainer.

There may be zero or more InlineContainer objects, each containing exactly one InlineHubClient. Any number of components can be directly embedded in a page.

The manager application interacts with the ManagedHub, Container and (optionally) HubPolicy objects via their public APIs. A Container exchanges messages with its HubClient in a proprietary fashion. The component within the Container interacts only with the Container’s HubClient and (optionally) HubPolicy, using these objects’ public APIs.

Managed Hub InitializationFigure 10 summarizes how an application initializes a ManagedHub instance, creates several containers, and directly/indirectly instantiates the Containers' HubClients. The figure shows one ManagedHub and two Containers. The Container on the left is an Iframe Container. The Container on the right is trusted by the manager application, so it has been hosted in an InlineContainer.

Component

(One per Container)

An application component such as a web widget that is embedded within a Manager Application. May be isolated inside an IframeContainer or embedded directly in the page using an InlineContainer.

PageBus.policy.HubPolicy

(Optional, one per HubClient)

A component or the Container infrastructure can associate a PageBus HubPolicy with the HubClient.

• Allows application to control the topics that the HubClient will allow to flow to and from the Managed Hub, based on the Manager Application’s origin


Element Description



Figure 10 Use of ManagedHub and HubClient

Managed Hub UsageFigure 11 summarizes how components communicate with each other via the Managed Hub framework. Component A, which the manager application does not trust, is securely isolated in an IframeContainer.

Figure 11 Publishing a message through the Managed Hub


Overview | 39

Types of ContainersSecurity has a price. In addition to providing different levels of security, the different Container types have other characteristics, such as performance and memory use. The following table summarizes the characteristics of the built-in container types provided by TIBCO PageBus. The following table summarizes the features of the built-in container types that ship with TIBCO PageBus.

Iframe Container: Fragment Identifier Messaging (FIM) vs. PostMessage

The Iframe Container uses one of two mechanisms to marshal messages across the iframe boundary:

• HTML postMessage:

Table 6 Features of built-in container types

Iframe Container Inline Container

Description Component is hosted within a separate page, in an iframe with a different origin from that of the manager application. IframeContainer and IFrameHubClient exchange messages by marshaling them into strings and transmitting them across the iframe boundary (see below).

Component is embedded in a DIV or other HTML element within the manager application’s page.

Security Securely isolates component. Used when mash-up does not completely trust component or component does not completely

No isolation. Component can directly access DOM, script, web services, etc. of manager application.

Performance Slower

• Initializes more slowly because iframes require round trips to the web server.

• Marshaling messages into strings and transmitting them is always slower than direct function calls.

• postMessage performs better than FIM (see below)

Faster.

Messages are delivered through direct function calls.

Memory Use More Less



If the web browser supports the recently introduced postMessage() function, the IframeContainer implementation uses postMessage() to transmit events from one window to another.

• Fragment Identifier Messaging (FIM):

If the browser does not support postMessage, then the IframeContainer implementation sends messages to the IframeHubClient by encoding them in the iframe’s src URL. It does this by appending a hash character (#) followed by the encoded message. The IframeHubClient periodically checks the URL for changes. A nested iframe (“tunnel iframe”) allows the HubClient to send messages back to the Container, which periodically checks for them.

PostMessage is the preferred mechanism, because Fragment Identifier Messaging has drawbacks, including relatively slow performance and potential disruptions when the Back button is used. See the section Browser-specific behavior on page 131 for more information.

Iframe Container: Tunnel Iframe

The Iframe Container contains a nested iframe called the Tunnel Iframe, whose origin is identical to that of the manager application. In the FIM case, the tunnel allows the component in the sandbox window to send messages to the ManagedHub by manipulating the fragment portion of its URL. In the postMessage case, this iframe facilitates secure connect and disconnect.

Choosing Container Types

You can use more than one type of Container per Managed Hub. For example, you can use Inline Containers for three components and Iframe Containers for two other components.

Use an Inline Container only if the component hosted in the Container is exactly as trustworthy as the mash-up that contains it. If either the mash-up or the component needs to be able to access any service or information that must be denied to the other for security reasons, then an Iframe Container must be used.


Overview | 41

Loading the PageBus JavaScriptThe PageBus logic can be loaded in several different ways:

When an Iframe Container is used, there will also be a HTML file, located at

pagebus/full/tunnel.html

This page is loaded inside the Tunnel Iframe discussed in the previous section.

Sample Source Code: Manager ApplicationThe following code snippet shows how a manager application instantiates a ManagedHub and some Container instances and grants them publish and subscribe privileges.

<html><head>



<script type="text/javascript" src="../pagebus/full/pagebus.js"></script>

Table 7 Loading PageBus JavaScript files

To load the following Load the following JavaScript files, in exactly the specified sequence

The whole Managed Hub in one file

pagebus/full/pagebus.js

The Managed Hub modules separately

• pagebus/hub/OpenAjax-mashup.js

• pagebus/hub/containers/inline/inline.js

• pagebus/hub/containers/iframe/iframe.js

• pagebus/hub/containers/iframe/FIM.js

• pagebus/hub/containers/iframe/crypto.js

• pagebus/hub/containers/iframe/json2.js

• pagebus/nohub/pagebus.js

You must load pagebus.js immediately after the containers and OpenAjax-mashup.js

Only the Simple PageBus API, not the Managed Hub

pagebus/simple/pagebus.js



<script type=”text/javascript”>

// The following function is invoked when a security alert is// raisedonSecurityAlert = function( source, alertType ) {

/* do something */ };

// Custom security management and/or other hook logiconPublish = function( topic, data, pc, sc ) { return true; };

// Custom security management and/or other hook logiconSubscribe = function( topic, sc ) { return true; };

// Handle onLoad eventloadEventHandler = function() {var S = PageBus.policy.Ops.Subscribe;var P = PageBus.policy.Ops.Publish;

// Create a HubPolicy and grant some permissionsvar pol = new PageBus.policy.HubPolicy( {} );pol.grant( “http://sandbox1.example.com”, P, “example.geo.country.*” );pol.grant( “http://sandbox1.example.com”, S, “x.y.z” );pol.grant( “http://mashup.example.com”, S, “example.geo.country.*” );pol.grant( “http://mashup.example.com”, P, “x.y.*” );

// Create a ManagedHubvar mhParams = {

onSecurityAlert: onSecurityAlert,onPublish: onPublish,onSubscribe: onSubscribe,PageBus: { policy: pol }

};var mh = new OpenAjax.hub.ManagedHub( mhParams );

// Create a container for component Avar aParams = { parent: document.getElementById(“containerA”) };var a = new OpenAjax.hub.InlineContainer( mh, “A”, aParams );

// Create a container for component Bvar bParams = {

parent: document.getElementById(“containerB”),uri:

“http://sandbox1.example.com/sample/componentB/sandboxB.html ”,tunnelURI: “http://mashup.example.com/pagebus/full/tunnel.html”

};var b = new OpenAjax.hub.InlineContainer( mh, “B”, bParams );

};</script>

</head><body onLoad=”loadEventHandler();”>

<div id=”containerA”></div><div id=”containerB”></div>

</body>


Overview | 43

</html>

Sample Source Code: Inline ContainerThe following code snippet shows how a component may be instantiated when an Inline Container is used. The code instantiates an InlineHubClient object. It runs within the manager application.

<script type=”text/javascript”>

// The following function is invoked when a security alert is // raisedOnSecurityAlert = function( source, alertType ) {

/* do something */ };

// Create the HubClientcaParms = {

HubClient: { onSecurityAlert: caOnSecurityAlert },InlineHubClient: {

container: a // We created container “a” in the // previous code snippet

},PageBus: {

policy: pol}

};caHub = new OpenAjax.hub.InlineHubClient( caParms );

// onData event handler for subscription belowonData = function( topic, message, subscriberData ) {

try {// Do something with message

} catch(e) { /* handle exceptions */ }};

// When caHub.connect() completes, this handler function is called.caOnConnect = function( hubClient, success, error ) {

if(success) {// Subscribe to a topichubClient.subscribe( “example.geo.country.select”, onData );

}}// Connect to the ContainercaHub.connect( caOnConnect );

</script>



Iframe Client Sample

The following code snippet shows how a component may be instantiated when an Iframe Container is used. This code runs within a separate web page inside the Container’s iframe window.

<html><head><script type=”text/javascript” src=”../pagebus/pagebus-full .js”></script><script type=”text/javascript”>// The following function is invoked when a security alert is // raisedcaOnSecurityAlert = function( source, alertType ) {

/* do something */ };var S = PageBus.policy.Ops.Subscribe;var P = PageBus.policy.Ops.Publish;// Create a PageBus HubPolicy object and grant privileges // for all topicsvar pol = new PageBus.policy.HubPolicy();pol.grant( “http://mashup.example.com”, S, “**” );pol.grant( “http://mashup.example.com”, P, “**” );// Create the HubClientcbParms = {

HubClient: { onSecurityAlert: caOnSecurityAlert },PageBus: { policy: pol }};cbHub = new OpenAjax.hub.InlineHubClient( cbParms );// onData event handler for subscription belowonData = function( topic, message, subscriberData ) {try {// Do something with message} catch(e) { /* handle exceptions */ }};// When cbHub.connect() completes, this handler function is called.cbOnConnect = function( hubClient, success, error ) {

if(success) {// Subscribe to a topichubClient.publish( “example.geo.country.select”, “US” );

}}// Connect to the ContainercbHub.connect( cbOnConnect );</script></head><body></body></html>


| 45

Chapter 4 Managed Hub API Reference

This chapter contains reference information for the Managed Hub APIs.

Topics

• The OpenAjax Hub 2.0 Specification Managed Hub APIs, page 46

• JSDoc Conventions, page 47

• Introduction the Managed Hub APIs, page 49

• OpenAjax.hub.Error, page 51

• OpenAjax.hub.SecurityAlert, page 52

• OpenAjax.hub.Hub, page 56

• OpenAjax.hub.ManagedHub, page 63

• OpenAjax.hub.Container, page 72

• OpenAjax.hub.IframeContainer, page 78

• OpenAjax.hub.InlineContainer, page 81

• OpenAjax.hub.HubClient, page 83

• OpenAjax.hub.IframeHubClient, page 87

• OpenAjax.hub.InlineHubClient, page 88


46 | Chapter 4 Managed Hub API Reference

The OpenAjax Hub 2.0 Specification Managed Hub APIs

This chapter directly incorporates content from the OpenAjax Hub 2.0 "Managed Hub API" specification. This documentation is mostly provided verbatim; it has been modified only in a few places, primarily to incorporate optional TIBCO PageBus extensions associated with caching and policy or to format content so that it fits gracefully on the page.

The specification can also be found online at the following location: http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Managed_Hub_APIs


http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Managed_Hub_APIs

http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Managed_Hub_APIs

JSDoc Conventions | 47

JSDoc Conventions

Some of the APIs defined in this chapter use JSDoc commenting conventions to describe various details about a particular API, such as a method's parameters, return values and exceptions. The JSDoc commenting conventions are described in this section and in the OpenAjax Hub 2.0 Specification at this location: http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Introduction#JSDoc_Conventions.

Here is an example that illustrates the use of JSDoc commenting conventions:

/** * Returns the client ID of this HubClient * * @returns clientID * @type {String} */OpenAjax.hub.HubClient.prototype.getClientID = function() {}

The JSDoc code above identifies the method name (OpenAjax.hub.HubClient.prototype.getClientID), a description for this method (i.e., "Returns the client ID of this HubClient"), and the value returned by the method (i.e., a JavaScript String object).

This specification uses the following subset of JSDoc: (Note: This subset is designed to align with the JSDoc syntax defined by JSDoc Toolkit version 2.1 (http://code.google.com/p/jsdoc-toolkit/.):

• At the bottom of the API definition is the name of the specified interface, in the form of a JavaScript function definition. The function definition shows the parameters to the function, with an empty function body (i.e., the function body is {}).

• Above the function definition are JavaScript comments that conform to JSDoc document commenting conventions, where the comment begins with the characters /** and ends with the characters */ .

• Any textual comments that do not begin with a JSDoc tag (A JSDoc "tag" is a keyword that begins with the @ character, such as @param) represent free-form descriptions of the given API.


http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Introduction#JSDoc_Conventions

http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Introduction#JSDoc_Conventions

http://code.google.com/p/jsdoc-toolkit/


• This chapter uses the following JSDoc tags:

— @param {type} name Specifies a parameter to a function.

— @returns Specifies the value returned by a function.

— @type {type} An @type immediately after an @returns specifies the datatype of the return value.

— @see Specifies a reference to other documentation.

— @throws {type} Specifies an exception that a function might throw.

Notes

• The {type} is an ECMAScript datatype, such as {Object} or {String}. A value of {*} indicates any JavaScript value . A vertical bar represents an OR condition. For example: {Function|String}.

• The Description is free-form text that provides a textual description. The Description might appear on the same line of the tag and/or might appear on one or more immediately following lines.

• Optional parameters are defined by surrounding the parameter name in square brackets, as in @param {*} [subscriberData].

When parameters are Objects, such as the params object required by OpenAjax.hub.Container:

@param {Object} params

the properties of the Object parameter are specified using separate @param tags:

@param {String} params.IframeContainer.tunnelURI


Introduction the Managed Hub APIs | 49

Introduction the Managed Hub APIs

This chapter provides descriptions of the various APIs within the Managed Hub.

Table 8 summarizes the classes, interfaces and singleton objects that comprise the Managed Hub APIs:

Table 8 Managed Hub APIs

API

Class, Singleton, or Interface?

Implements/Extends Description

OpenAjax.hub.Error Singleton N/A Provides the list of error codes used by the various classes and interfaces that make up the Managed Hub

OpenAjax.hub.SecurityAlert Singleton N/A Provides the list of standard codes used when attempted security violations are detected

OpenAjax.hub.Hub Interface N/A Interface that defines the APIs shared by OpenAjax.hub.ManagedHub and OpenAjax.hub.HubClient

OpenAjax.hub.ManagedHub Class Implements OpenAjax.hub.Hub

Manager Application uses this API to interact with Managed Hub

OpenAjax.hub.Container Interface N/A Base class for all Containers.Subclasses include OpenAjax.hub classesIframeContainer andInlineContainer (see below)

OpenAjax.hub.IframeContainer Class Implements OpenAjax.hub.Container

Built-in container type that securely isolates components by placing components into their own iframes. Iframes have different (sub)domains than the main application and, usually, from other components' iframes.



Within this chapter, the following terms have the following meanings:

Class A collection of related JavaScript logic that allows for object instantiation via the 'new' operator. For the APIs defined in this chapter, a class consists of:

• A constructor function (e.g., function MyClass(...) {...}) whose name matches the name of the class (i.e., MyClass). An object instance of the class can be instantiated by using the 'new' operator. For example: var MyObject = new MyClass(...);.

• Class methods defined on the class object prototype (e.g., MyClass.prototype.method1 = function(...) {...}).

Interface A related collection of APIs that an implementing class must implement.

Singleton A JavaScript object that provides APIs. As the name suggests, there is only one instance of a singleton.

OpenAjax.hub.InlineContainer Class Implements OpenAjax.hub.Container

Built-in Container type that does not isolate components. Components are inserted directly within an HTML element (e.g. a DIV) within a page of the Manager Application.

OpenAjax.hub.HubClient Interface Extends OpenAjax.hub.Hub

API that a component uses to interact with the Managed Hub

OpenAjax.hub.IframeHubClient Class Implements OpenAjax.hub.HubClient

HubClient implementation that corresponds to IframeContainer

OpenAjax.hub.InlineHubClient Class Implements OpenAjax.hub.HubClient

HubClient implementation that corresponds to InlineContainer

Table 8 Managed Hub APIs

API

Class, Singleton, or Interface?

Implements/Extends Description


OpenAjax.hub.Error | 51

OpenAjax.hub.Error

OpenAjax.hub.Error holds the list of errors thrown by the PageBus APIs.

OpenAjax.hub.Error = { // Either a required argument is missing or an invalid

// argument was provided BadParameters: "OpenAjax.hub.Error.BadParameters", // The specified hub has been disconnected and cannot

// perform the requested operation: Disconnected: "OpenAjax.hub.Error.Disconnected", // Container with specified ID already exists: Duplicate: "OpenAjax.hub.Error.Duplicate", // The specified ManagedHub has no such Container

// (or it has been removed) NoContainer: "OpenAjax.hub.Error.NoContainer", // The specified ManagedHub or Container has

// no such subscription NoSubscription: "OpenAjax.hub.Error.NoSubscription", // Permission denied by manager's security policy NotAllowed: "OpenAjax.hub.Error.NotAllowed", // Wrong communications protocol identifier

// provided by Container or HubClient WrongProtocol: "OpenAjax.hub.Error.WrongProtocol"};



OpenAjax.hub.SecurityAlert

OpenAjax.hub.SecurityAlert holds the list of standard codes used when attempted security violations are detected. Unlike Errors, these codes are not thrown as exceptions but rather passed into the SecurityAlertHandler function registered with the Hub instance.

OpenAjax.hub.SecurityAlert = { // Container did not load (possible frame phishing attack) LoadTimeout: "OpenAjax.hub.SecurityAlert.LoadTimeout", // Hub suspects a frame phishing attack against the

// specified container FramePhish: "OpenAjax.hub.SecurityAlert.FramePhish", // Hub detected a message forgery reported by a

// specified container. ForgedMsg: "OpenAjax.hub.SecurityAlert.ForgedMsg"};

Common callback functions

OpenAjax.hub.onSecurityAlert callback function

Hub components use onSecurityAlert callback functions to notify application components when they have blocked serious attacks such as message forgery or frame phishing. While a security alert indicates that an attack has been prevented, applications SHOULD react quite forcefully when security alerts occur. For more details, see Security Alerts on page 124 in Chapter 8, Best Practices and FAQs.

/** * onSecurityAlert callback for ManagedHub, Container and HubClient * Invoked when a * security alert is raised. * Supplied to ManagedHub, Container and HubClient constructor via * the onSecurityAlert parameter * * @param {Object} source * The Container or HubClient instance that raised the security * alert * @param {OpenAjax.hub.SecurityAlert} alertType * The type of alert */OpenAjax.hub.onSecurityAlert= function( source, alertType ) {}

The value of the source parameter is:

• A Container instance, if a Container instance thwarts an attack


OpenAjax.hub.SecurityAlert | 53

• A HubClient instance, if a HubClient instance thwarts the attack

When an onSecurityAlert callback is invoked, the JavaScript this keyword refers to source.getScope().

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.log callback function

Logging helps developers to troubleshoot their applications. The constructors for ManagedHub, Container and HubClient allow the caller to specify optional logger callback functions.

/** * The scope of the log function is the same as that of the * object with which it is * associated. If the log function is associated with a * Container, then in the log * function, the JavaScript "this" keyword refers to * the params.Container.scope * that was passed into the Container constructor. * * @param {String} messageString The message to be logged */OpenAjax.hub.log= function( messagestring ) {}

In most cases, logger callback functions simply call console.log. However, console.log is not fully portable, so other implementations may be needed in some environments.

Log messages:

• are technical in nature

• are unsuitable for end users

• are not necessarily localized

• contain content that is not defined by any standard and may differ from one implementation or version to another.

Thus, a log callback function SHOULD only be supplied during developer troubleshooting, and application code SHOULD NOT parse log messages and make decisions based on their contents.

This type of callback function SHOULD NOT throw exceptions.



Host applications that use the Hub SHOULD code their log functions carefully to prevent cross-site scripting (XSS) attacks. In particular, host applications SHOULD avoid simple innerHTML assignments of the log messages to prevent malicious components from injecting executable content (e.g., a <script> element) through the logging mechanism.

OpenAjax.hub.onComplete callback function

Many Hub operations are asynchronous. For such operations, the only reliable way to determine when the operation completes, and whether it succeeds or fails, is to provide an onComplete callback function when invoking the operation.

/** * An onComplete callback function is invoked when an * asynchronous API call, * such as HubClient.connect() or HubClient.subscribe(), completes. * When the callback is invoked, the JavaScript "this" * keyword refers to the * object specified in the scope parameter of the * asynchronous API call. * * @param {*} item * Item on which the completed operation was invoked * @param {Boolean} success * If operation succeeded (item is active) then * true, else false * @param {OpenAjax.hub.Error} errCode * If success != true, then contains a string error * code, else is undefined */onComplete = function(item, success, errCode) {}

Example parameter values for HubClient.subscribe:

// Example of success:foo.onComplete(subscriptionID, true);

// Example of failure:foo.onComplete(subscriptionID, false, "OpenAjax.hub.Error.NotAllowed");

When an onComplete callback function is invoked, the item parameter is either a HubClient or a subscription ID, depending on the operation with which the onComplete function is associated.

Notes about error codes:


OpenAjax.hub.SecurityAlert | 55

• The string error code is either one of the error codes listed in OpenAjax.hub.Error or a more specialized error code defined by the HubClient implementation.

• HubClients SHOULD use the standard error codes rather than providing their own overlapping ones.

• A HubClient implementation MAY define ADDITIONAL error codes for specialized situations that are only encountered in that particular implementation of HubClient.




OpenAjax.hub.Hub

The OpenAjax.hub.Hub interface is a base interface that is implemented on the manager side by OpenAjax.hub.ManagedHub. On the client side, OpenAjax.hub.HubClient extends OpenAjax.hub.Hub.

OpenAjax.hub.Hub.prototype.subscribe

subscribe creates a subscription on the specified topic name.

/** * Subscribe to a topic. * * @param {String} topic * A valid topic string. MAY include wildcards. * @param {Function} onData * Callback function that is invoked whenever an event is * published on the topic * @param {Object} [scope] * When onData callback or onComplete callback is invoked, * the JavaScript "this" keyword refers to this scope object. * If no scope is provided, default is window. * @param {Function} [onComplete] * Invoked to tell the client application whether the * subscribe operation succeeded or failed. * @param {*} [subscriberData] * Client application provides this data, which is handed * back to the client application in the subscriberData * parameter of the onData callback function. * * @returns subscriptionID * Identifier representing the subscription. This * identifier is an * arbitrary ID string that is unique within this Hub instance * @type {String} * * @throws {OpenAjax.hub.Error.Disconnected} if this Hub * instance is not in CONNECTED state * @throws {OpenAjax.hub.Error.BadParameters} if the topic * is invalid (e.g. contains an empty token) */OpenAjax.hub.Hub.prototype.subscribe = function( topic, onData, scope, onComplete, subscriberData ) {}


OpenAjax.hub.Hub | 57

If an onComplete callback function has been provided, then, when the operation completes, the onComplete callback function is called. If the operation was successful, then the subscription is now "active," and the Hub can deliver published events by calling the onData callback function. On the other hand, if the subscribe operation failed, the subscription is now "inactive." The hub calls the onComplete callback function to report the error and then destroys the subscription.

In most Container implementations, subscribe operates asynchronously, so that the onComplete function typically is called after the subscribe function returns. In some implementations, however, subscribe operates synchronously, invoking onComplete before it returns. Applications that use this function SHOULD be programmed so that they can work with any Container (Iframe, Inline, or other). In order to handle the various possibilities, publishers and subscribers MUST follow certain practices, which are described in the "Publish Subscribe Best Practices" chapter.

If unsubscribe is called before the subscribe operation completes, then the Hub implementation does not invoke the onComplete callback for the subscribe operation if an unsubscribe operator has occurred before the subscribe operation has completed (e.g., due to a call to the hubClient.unsubscribe() method).

If the subscriberData parameter is an object, and the object contains a property PageBus: { cache: true }

then the subscription that is created will be cache-enabled.

OpenAjax.hub.onData callback function

To deliver a published event to a subscriber, a Hub invokes the subscriber's onData callback function. When this callback is invoked, the JavaScript this keyword refers to the scope parameter that was supplied in the subscribe call. If no scope parameter was specified, then the default scope is window.

/** * onData callback functions * * @param {String} topic * The topic on which the event was published * @param {*} data * The event "payload" data. Can be any * JSON-serializable value. * @param {*} subscriberData * The 'subscriberData' value that the caller * supplied to the subscribe() call */onData = function( topic, data, subscriberData ) {}

This type of callback function SHOULD NOT throw exceptions.



The callback function SHOULD always regard the data parameter as read-only, even if it is an object or array.

OpenAjax.hub.Hub.prototype.publish

This function publishes a data event on a topic.

/** * Publish an event on a topic * * @param {String} topic * A valid topic string. MUST NOT include wildcards. * @param {*} data * Valid publishable data. To be portable across different * Container implementations, this value should be serializable * as JSON. * * @throws {OpenAjax.hub.Error.Disconnected} if this Hub * instance is not in CONNECTED state * @throws {OpenAjax.hub.Error.BadParameters} if the topic * cannot be published (e.g. contains * wildcards or empty tokens) or if the data cannot be * published (e.g. cannot be serialized as JSON) */OpenAjax.hub.Hub.prototype.publish = function( topic, data ) {}

The publish function immediately throws an exception if the topic or data cannot be published or if the Hub is not connected. Otherwise, the operation continues.

In most Container implementations, publish operates asynchronously, so that data is delivered to subscribers after the publish function returns. In some implementations, however, publish operates synchronously, delivering its data to the subscribers before returning. Applications that use this function SHOULD be programmed so that they can work with any Container (Iframe, Inline, or other). In order to handle the various possibilities, publishers and subscribers MUST follow certain practices, which are described in the "Publish Subscribe Best Practices" chapter.

When the implementation prevents a data item published by a client from being delivered to a subscriber, the publishing Client Application is NOT notified in any way. When a Client Application publishes, it cannot determine how many subscribers exist and it cannot determine how many of the existing subscribers received the published data item.

The data parameter is owned by the caller. The publish function does not modify it and the caller may continue to use it after publish() returns.



OpenAjax.hub.Hub.prototype.unsubscribe

Unsubscribe cancels an existing subscription.

/** * Unsubscribe from a subscription * * @param {String} subscriptionID * A subscriptionID returned by Hub.subscribe() * @param {Function} [onComplete] * Callback function invoked when unsubscribe completes * @param {Object} [scope] * When onComplete callback function is invoked, * the JavaScript "this" * keyword refers to this scope object. * If no scope is provided, default is window. * * @throws {OpenAjax.hub.Error.Disconnected} if this Hub * instance is not in CONNECTED state * @throws {OpenAjax.hub.Error.NoSubscription} * if no such subscription is found */OpenAjax.hub.Hub.prototype.unsubscribe = function( subscriptionID, onComplete, scope ) {}

The unsubscribe function immediately throws an exception if there is no subscription with the specified subscription ID. Otherwise, unsubscribe immediately deactivates the subscription. Once unsubscribe is called:

• The onData and onComplete callback functions registered via subscribe will no longer be invoked.

• Operations that require that the subscription be "active" throw OpenAjax.hub.Error.Disconnected.

When the unsubscribe operation completes, the onComplete function is invoked. In asynchronous implementations (e.g. OpenAjax.hub.IframeHubClient), this callback typically is invoked after the unsubscribe function returns. In synchronous implementations, such as ManagedHub and OpenAjax.hub.InlineClient, this callback typically is invoked before the unsubscribe function returns.

Note: Because unsubscribe immediately deactivates the subscription, whereas publish and subscribe might happen asychronously, in some implementations and/or on particular browsers the following sequence may result in the subscription being cancelled before the publishing event is completed:

function MyCallback(topic, data, subscriberData) {...}var subscriptionID = hubClient.subscribe("org.example.topics.something", MyCallback);



// Because publishing to a subscriber can be asynchronous // whereas unsubscribe// operations are immediate, the subscription // above might be cancelled by the // unsubscribe call below before the publish operation // invokes the subscribe callback hubClient.publish("org.example.topics.something", somedata); hubClient.unsubscribe(subscriptionID);

OpenAjax.hub.Hub.prototype.isConnected

isConnected tells the caller whether the Hub is connected or not.

/** * Return true if this Hub instance is in the Connected state. * Else returns false. * * This function can be called even if the Hub is * not in a CONNECTED state. * * @returns Boolean * @type {Boolean} */OpenAjax.hub.Hub.prototype.isConnected = function() {}

This function MAY be called even when the Hub instance is not connected.

OpenAjax.hub.Hub.prototype.getScope

/** * Returns the scope associated with this Hub instance * and which will be used * with callback functions. * * This function can be called even if the Hub is * not in a CONNECTED state. * * @returns scope object * @type {Object} */OpenAjax.hub.Hub.prototype.getScope = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Hub.prototype.getSubscriberData

This function returns the subscriberData associated with a subscription.



/** * Returns the subscriberData parameter that was provided when * Hub.subscribe was called. * * @param {String} subscriberID * The subscriberID of a subscription * * @returns subscriberData * @type {*} * * @throws {OpenAjax.hub.Error.Disconnected} if this * Hub instance is not in CONNECTED state * @throws {OpenAjax.hub.Error.NoSubscription} if * there is no such subscription */OpenAjax.hub.Hub.prototype.getSubscriberData= function(subscriptionID) {}


OpenAjax.hub.Hub.prototype.getSubscriberScope

This function returns the scope object associated with a subscription.

/** * Returns the scope associated with a specified * subscription. This scope will * be used when invoking the 'onData' callback * supplied to Hub.subscribe(). * * @param {String} subscriberID * The subscriberID of a subscription * * @returns scope * @type {*} * * @throws {OpenAjax.hub.Error.Disconnected} if this * Hub instance is not in CONNECTED state * @throws {OpenAjax.hub.Error.NoSubscription} * if there is no such subscription *///OpenAjax.hub.Hub.prototype.getSubscriberScope = function(subscriberID) {}


OpenAjax.hub.Hub.prototype.getParameters

This function returns the params object associated with this Hub instance.



/** * Returns the params object associated with this Hub instance. * * @returns params * The params object associated with this Hub instance * @type {Object} *///OpenAjax.hub.Hub.prototype.getParameters = function() {}

This function returns the parameters object that was specified when the Hub instance was constructed.


OpenAjax.hub.ManagedHub | 63

OpenAjax.hub.ManagedHub

The class OpenAjax.hub.ManagedHub implements OpenAjax.hub.Hub and provides manager-side APIs to the Managed Hub. Most ManagedHub functions are synchronous; in particular, functions that support onComplete callbacks invoke these callbacks before returning control to the caller.

OpenAjax.hub.ManagedHub constructor

/*** Create a new ManagedHub instance* @constructor** This constructor automatically sets the ManagedHub's state to* CONNECTED.** @param {Object} params* Parameters used to instantiate the ManagedHub.* Once the constructor is called, the params* object belongs exclusively to* the ManagedHub. The caller MUST not modify it.** The params object may contain the following properties:** @param {Function} params.onPublish* Callback function that is invoked whenever a* data value published by a Container is about* to be delivered to some (possibly the same) Container.* This callback function implements a security policy;* it returns true if the delivery of the data is* permitted and false if permission is denied.* @param {Function} params.onSubscribe* Called whenever a Container tries to subscribe* on behalf of its client.* This callback function implements a security policy;* it returns true if the subscription is permitted* and false if permission is denied.* @param {Function} [params.onUnsubscribe]* Called whenever a Container unsubscribes on* behalf of its client.* Unlike the other callbacks, onUnsubscribe is* intended only for* informative purposes, and is not used to* implement a security* policy.* @param {Object} [params.scope]* Whenever one of the ManagedHub's callback* functions is called,* references to the JavaScript "this" keyword in the callback* function refer to this scope object* If no scope is provided, default is window.* @param {Function} [params.log] Optional logger function. Would



* be used to log to console.log or equivalent.* @param {Object} [params.PageBus]* PageBus specific configuration for ManagedHub instance* @param {PageBus.policy.HubPolicy} [params.PageBus.policy]* Security policy object. This object implements onPublish* and onSubscribe functions.* @param {Function} [params.PageBus.log]* Logger callback function** @throws {OpenAjax.hub.Error.BadParameters}* if any of the required parameters are missing*/OpenAjax.hub.ManagedHub = function( params ) {}

A ManagedHub instance makes use of the params properties throughout its lifetime, and NOT just before the constructor returns. For example, the onPublish function will be invoked long after the constructor returns.

A ManagedHub is already in the connected state when the constructor returns.

The ManagedHub constructor's params object can also include an optional pagebus sub-object containing PageBus-specific parameters. These include a policy property that contains a HubPolicy object, and a logger function for debug logging of PageBus actions.

The HubPolicy object is documented in the next section. If provided, this security manager object implements additional onPublish and onSubscribe functions for the ManagedHub. You still implement additional onPublish and onSubscribe functions, which are called at the end of the HubPolicy's function calls.

OpenAjax.hub.ManagedHub onPublish callback function

An onPublish callback function defines a custom policy that controls which clients are allowed to send data on which topics to which clients. When creating a new ManagedHub, the Manager Application can specify an onPublish policy function.

/** * onPublish callback for ManagedHub * Invoked within the scope defined by ManagedHub.getScope(), * when a * ManagedHub client publishes an event via publishForClient * and the published * data is to be delivered to a second client * Supplied to ManagedHub constructor via the params.onPublish* parameter * * @param {String} topic * The topic to which the first container is publishing * @param {*} data * The data that the first container is publishing



* @param {OpenAjax.hub.Container} pcont * The container that is publishing (if the publisher * is the Manager Application, pcont is null) * @param {OpenAjax.hub.Container} scont * The container to which the data is about to be * delivered (if this is the Manager Application, * scont is null) * * @returns true if the delivery of the data is allowed, else false * @type {boolean} */OpenAjax.hub.onPublish = function( topic, data, pcont, scont ) {}

This function is invoked when the ManagedHub attempts to deliver a published event to one subcriber. Thus, if there are one publisher and 3 subscribers, onPublish will be called three times per event.


This function is invoked when EITHER ManagedHub.publishForClient or ManagedHub.publish is called.

When ManagedHub.publish is called, the pcont parameter of the onPublish callback is null. When the subscription belongs to the manager application rather than to a Container, the scont parameter of the onPublish callback is null.

OpenAjax.hub.ManagedHub onSubscribe callback function

An onSubscribe callback function defines a custom policy that controls which clients are allowed to subscribe to which topics. When creating a new ManagedHub, the Manager Application can specify an onSubscribe policy function.

/** * onSubscribe callback for ManagedHub * Invoked within the scope defined by ManagedHub.getScope(), * when a ManagedHub client subscribes via subscribeForClient. * Supplied to ManagedHub constructor via the * params.onSubscribe parameter * * @param {String} topic * The topic to which the container is subscribing * @param {OpenAjax.hub.Container} container * The container that is subscribing * * @returns true if the subscribe is allowed, else false * @type {boolean} */OpenAjax.hub.onSubscribe = function( topic, container ) {}



When the onSubscribe callback function is called, the JavaScript this keyword is the object returned by ManagedHub.getScope().


This function is invoked when EITHER ManagedHub.subscribeForClient or ManagedHub.subscribe is called. When ManagedHub.subscribe is called, the container parameter of the onSubscribe callback is null.

OpenAjax.hub.ManagedHub onUnsubscribe callback function

An onUnsubscribe callback function alerts the Manager Application when a client unsubscribes from a topic.

/** * onUnsubscribe callback for ManagedHub * Invoked within the scope defined by ManagedHub.getScope(), when* a * ManagedHub client unsubscribes via unsubscribeForClient. * Supplied to ManagedHub constructor via the * params.onUnsubscribe parameter. * * @param {String} topic * The topic to which the container is unsubscribing * @param {OpenAjax.hub.Container} container * The container that is unsubscribing */OpenAjax.hub.onUnsubscribe = function( topic, container ) {}

When the onUnsubscribe callback function is called, the JavaScript this keyword is the object returned by ManagedHub.getScope().


This function is invoked when EITHER ManagedHub.unsubscribeForClient or ManagedHub.unsubscribe is called.

When ManagedHub.unsubscribe is called, the container parameter of the onUnsubscribe callback is null.



OpenAjax.hub.ManagedHub.prototype.subscribeForClient

This function is called only by Container implementations. Manager Applications SHOULD NOT invoke it. This function subscribes to a topic on behalf of a Container.

/** * Subscribe to a topic on behalf of a Container. Called only by * Container implementations, NOT by manager applications. * * This function: * 1. Checks with the ManagedHub's onSubscribe security policy * to determine whether this Container is allowed to subscribe * to this topic. * 2. If the subscribe operation is permitted, subscribes to the * topic and returns the ManagedHub's subscription ID for this * subscription. * 3. If the subscribe operation is not permitted, throws * OpenAjax.hub.Error.NotAllowed. * * When data is published on the topic, the ManagedHub's * onPublish security policy will be invoked to ensure that * this Container is permitted to receive the published data. * If the Container is allowed to receive the data, then the * Container's sendToClient function will be invoked. * * When a Container needs to create a subscription on behalf of * its client, the Container MUST use this function to create * the subscription. * * @param {OpenAjax.hub.Container} container * A Container * @param {String} topic * A valid topic * @param {String} containerSubID * Arbitrary string ID that the Container uses to * represent the subscription. Must be unique within the * context of the Container * * @returns managerSubID * Arbitrary string ID that this ManagedHub uses to * represent the subscription. Will be unique within the * context of this ManagedHub * @type {String} * * @throws {OpenAjax.hub.Error.Disconnected} if this.isConnected()* returns false * @throws {OpenAjax.hub.Error.NotAllowed} if subscription request* is denied by the onSubscribe security policy * @throws {OpenAjax.hub.Error.BadParameters} if one of the* parameters, e.g. the topic, is invalid */OpenAjax.hub.ManagedHub.prototype.subscribeForClient = function( container, topic, containerSubID ) {}



If unsubscribeForClient is called before the subscribeForClient operation completes, then the implementation MUST NOT invoke the subscribeForClient function's onComplete callback.

OpenAjax.hub.ManagedHub.prototype.unsubscribeForClient

This function is called only by Container implementations. Manager Applications SHOULD NOT invoke it. This function terminates a subscription on behalf of a Container.

/** * Unsubscribe from a subscription on behalf of a Container. * Called only by * Container implementations, NOT by manager application code. * * This function: * 1. Destroys the specified subscription * 2. Calls the ManagedHub's onUnsubscribe callback function * * This function can be called even if the ManagedHub is * not in a CONNECTED state. * * @param {OpenAjax.hub.Container} container * container instance that is unsubscribing * @param {String} managerSubID * opaque ID of a subscription, returned by previous * call to subscribeForClient() * * @throws {OpenAjax.hub.Error.NoSubscription} if subscriptionID* does not refer to a valid subscription */OpenAjax.hub.ManagedHub.prototype.unsubscribeForClient = function( container, managerSubID ) {}

Implementations are not required to verify that the specified subscription belongs to the specified Container.

OpenAjax.hub.ManagedHub.prototype.publishForClient

This function is called only by Container implementations. Manager Applications SHOULD NOT invoke it. This function publishes a data event to a topic on behalf of a Container.

/** * Publish data on a topic on behalf of a Container. Called only by * Container implementations, NOT by manager application code. * * @param {OpenAjax.hub.Container} container



* Container on whose behalf data should be published * @param {String} topic * Valid topic string. Must NOT contain wildcards. * @param {*} data * Valid publishable data. To be portable across different * Container implementations, this value SHOULD * be serializable as JSON. * * @throws {OpenAjax.hub.Error.Disconnected} if this.isConnected()* returns false * @throws {OpenAjax.hub.Error.BadParameters} if one of * the parameters, e.g. the topic, is invalid */OpenAjax.hub.ManagedHub.prototype.publishForClient = function( container, topic, data ) {}

For each subscription that is "owned" by a Container, this function invokes the ManagedHub's onPublish security policy to determine whether to forward the data to the subscriber. If the onPublish policy callback returns true, then data is forwarded to the subscriber. Otherwise, the data is not forwarded to the subscriber (although no error is generated).

OpenAjax.hub.ManagedHub.prototype.disconnect

This function disables the ManagedHub and allows the garbage collector to clean it up.

/** * Destroy this ManagedHub * * 1. Sets state to DISCONNECTED. All subsequent attempts to * add containers, * publish or subscribe will throw the Disconnected error. We will * continue to allow "cleanup" operations such as removeContainer * and unsubscribe, as well as read-only operations such as * isConnected * 2. Remove all Containers associated with this ManagedHub */OpenAjax.hub.ManagedHub.prototype.disconnect = function() {}


OpenAjax.hub.ManagedHub.prototype.getContainer

/** * Get a container belonging to this ManagedHub by its clientID, * or null * if this ManagedHub has no such container *



* This function can be called even if the ManagedHub is not * in a CONNECTED state. * * @param {String} containerId * Arbitrary string ID associated with the container * * @returns container associated with given ID * @type {OpenAjax.hub.Container} */OpenAjax.hub.ManagedHub.prototype.getContainer = function( containerId ) {}


OpenAjax.hub.ManagedHub.prototype.listContainers

/** * Returns an array listing all containers belonging to * this ManagedHub. * The order of the Containers in this array is arbitrary. * * This function can be called even if the ManagedHub is not * in a CONNECTED state. * * @returns container array * @type {OpenAjax.hub.Container[]} */OpenAjax.hub.ManagedHub.prototype.listContainers = function() {}


OpenAjax.hub.ManagedHub.prototype.addContainer

/** * Add a container to this ManagedHub. * * This function should only be called by a Container constructor. * * @param {OpenAjax.hub.Container} container * A Container to be added to this ManagedHub * * @throws {OpenAjax.hub.Error.Duplicate} if there * is already a Container * in this ManagedHub whose clientId is the same as * that of container * @throws {OpenAjax.hub.Error.Disconnected} if this.isConnected()* returns false */OpenAjax.hub.ManagedHub.prototype.addContainer = function( container ) {}




OpenAjax.hub.ManagedHub.prototype.removeContainer

/** * Remove a container from this ManagedHub immediately * * This function can be called even if the ManagedHub is * not in a CONNECTED state. * * @param {OpenAjax.hub.Container} container * A Container to be removed from this ManagedHub * * @throws {OpenAjax.hub.Error.NoContainer} if no * such container is found */OpenAjax.hub.ManagedHub.prototype. removeContainer = function( container ) {}

removeContainer does the following:

1. Invoke Container.remove to shut down the Container

2. Remove the Container from the Hub



OpenAjax.hub.Container

OpenAjax.hub.Container is an interface that MUST be implemented by all containers.

OpenAjax.hub.Container constructor

/** * Container * @constructor * * Container represents an instance of a manager-side object that* contains and communicates with a single client of the hub. The* container might be an inline container, an iframe FIM container,* or an iframe PostMessage container, or it might be an instance* of some other implementation. * * @param {OpenAjax.hub.ManagedHub} hub * Managed Hub instance * @param {String} clientID * A string ID that identifies a particular client of a Managed* Hub. Unique within the context of the ManagedHub. * @param {Object} params * Parameters used to instantiate the Container. * Once the constructor is called, the params object belongs* exclusively to the Container. The caller MUST not modify it. * Implementations of Container may specify additional* properties for the params object, besides those identified* below. * The following params properties MUST be supported by all* Container implementations:* * @param {Function} params.Container.onSecurityAlert * Called when an attempted security breach is thwarted. * Function is defined as follows: function(container,* securityAlert) * @param {Function} [params.Container.onConnect] * Called when the client connects to the Managed Hub. Function* is defined as follows: function(container) * @param {Function} [params.Container.onDisconnect] * Called when the client disconnects from the Managed Hub. * Function is defined as follows: function(container) * @param {Object} [params.Container.scope] * Whenever one of the Container's callback functions is called,* references to "this" in the callback will refer to the scope* object. If no scope is provided, default is window. * @param {Function} [params.Container.log] * Optional logger function. Would be used to log to console.log* or equivalent. * * @throws {OpenAjax.hub.Error.BadParameters} if required params* are not present or null * @throws {OpenAjax.hub.Error.Duplicate} if a Container with


OpenAjax.hub.Container | 73

* this clientID already exists in the given Managed Hub * @throws {OpenAjax.hub.Error.Disconnected} if ManagedHub is not* connected */OpenAjax.hub.Container = function( hub, clientID, params ) {}

A Container instance makes use of the params properties throughout its lifetime, and NOT just before the constructor returns. For example, the onSecurityAlert function is invoked whenever the Container instance prevents an attempted security breach, even if this happens long after the constructor returns.

OpenAjax.hub.Container onConnect callback function

/** * onConnect callback for Container * Invoked within the scope defined by params.Container.scope, when* the specified Container's client connects to the ManagedHub. * Supplied to Container constructor via the* params.Container.onConnect parameter * * @param {OpenAjax.hub.Container} container The Container that* detected the connect */OpenAjax.hub.ContainerCallbacks.onConnect = function( container ) {}

This type of callback function SHOULD NOT throw exceptions. TIBCO PageBus catches and ignores all exceptions thrown by this type of callback.

OpenAjax.hub.Container onDisconnect callback function

/** * onDisconnect callback for Container * Invoked within the scope defined by params.Container.scope, when* the specified Container's client disconnects from the* ManagedHub. * Supplied to Container constructor via the* params.Container.onDisconnect parameter * * @param {OpenAjax.hub.Container} container The Container that* detected the disconnect */OpenAjax.hub.ContainerCallbacks.onDisconnect = function( container ) {}



This type of callback function SHOULD NOT throw exceptions. TIBCO PageBus catches and ignores all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.Container.prototype.sendToClient

This function is called only by ManagedHub implementations. Manager Applications SHOULD NOT invoke it.

/** * Send a message to the client inside this container. This* function MUST only be called by ManagedHub. * * @param {String} topic * The topic name for the published message * @param {*} data * The payload. Can be any JSON-serializable value. * @param {String} containerSubscriptionId * Container's ID for a subscription, from previous call to * subscribeForClient() */OpenAjax.hub.Container.prototype.sendToClient = function(topic, data, containerSubscriptionId) {}


OpenAjax.hub.Container.prototype.remove

This function is called only by ManagedHub implementations. Manager Applications SHOULD NOT invoke it.

Manager application code should call ManagedHub.removeContainer() instead.

/** * Shut down a container. remove does all of the following: * - disconnects container from HubClient * - unsubscribes from all of its existing subscriptions in the* ManagedHub * * This function is only called by ManagedHub.removeContainer * Calling this function does NOT cause the container's* onDisconnect callback to be invoked. */OpenAjax.hub.Container.prototype.remove = function() {}




OpenAjax.hub.Container.prototype.isConnected

/** * Returns true if the HubClient owned by this container is* connected to the ManagedHub via this container.* Else returns false. * * @returns true if the client is connected to the managed hub * @type boolean */OpenAjax.hub.Container.prototype.isConnected = function() {}


OpenAjax.hub.Container.prototype.getClientID

/** * Returns the clientID passed in when this Container was* instantiated. * * @returns The clientID * @type {String} */OpenAjax.hub.Container.prototype.getClientID = function() {}


OpenAjax.hub.Container.prototype.getPartnerOrigin

/** * If DISCONNECTED: * Returns null * If CONNECTED: * Returns the origin associated with the window containing the* HubClient * associated with this Container instance. The origin has the* format * * [protocol]://[host] * * where: * * [protocol] is "http" or "https" * [host] is the hostname of the partner page. * * @returns Partner's origin * @type {String} */OpenAjax.hub.Container.prototype.getPartnerOrigin = function() {}



All of the leading web browsers prevent script running in a window from accessing the DOM/script of a window whose "origin" is different. This is an instance of the Same Origin Policy. Leading Web browsers prevent access if the two windows have different protocols or hosts.

Some browsers also prevent access if the two windows have different ports, but some do not. Others may allow large port numbers to wrap around in same origin checks.

In the interest of consistency, this function returns the "lowest common denominator" origin, i.e. "[protocol]://[host]". Two windows that have the same protocol and host but different ports will appear to share the same origin.

Example origins:

"http://www.openajax.org""https://mashexample.example.co.uk"

If the HubClient and Container are in the same window (InlineContainer) then the origin of the Container's partner is the origin of that window. If the client is in an iframe (IframeContainer) then the origin of the Container's partner is the origin of the iframe window.

OpenAjax.hub.Container.prototype.getParameters

This function returns the params object passed to the constructor that created this Container instance.

/** * Returns the params object associated with this Container* instance. * * @returns params * The params object associated with this Container instance * @type {Object} */OpenAjax.hub.Container.prototype.getParameters = function() {}


OpenAjax.hub.Container.prototype.getHub

This function returns the ManagedHub object associated with this Container instance.



/** * Returns the ManagedHub to which this Container belongs. * * @returns ManagedHub * The ManagedHub object associated with this Container instance * @type {OpenAjax.hub.ManagedHub} */OpenAjax.hub.Container.prototype.getHub = function() {}




OpenAjax.hub.IframeContainer

OpenAjax.hub.IframeContainer implements the OpenAjax.hub.Container interface to provide a container that isolates client components into secure sandboxes by leveraging the isolation features provided by browser Iframes.

OpenAjax.hub.IframeContainer constructor

/** * Create a new Iframe Container. * @constructor * * IframeContainer implements the Container interface to provide a* container that isolates client components into secure sandboxes* by leveraging the isolation features provided by browser* iframes. * * @param {OpenAjax.hub.ManagedHub} hub * Managed Hub instance to which this Container belongs * @param {String} clientID * A string ID that identifies a particular client of a Managed* Hub. Unique within the context of the ManagedHub. * @param {Object} params * Parameters used to instantiate the IframeContainer. * Once the constructor is called, the params object belongs* exclusively to the IframeContainer. The caller MUST not* modify it. * The following are the pre-defined properties on params: * @param {Function} params.Container.onSecurityAlert * Called when an attempted security breach is thwarted. * Function is defined as follows: function(container,* securityAlert) * @param {Function} [params.Container.onConnect] * Called when the client connects to the Managed Hub. Function* is defined as follows: function(container) * @param {Function} [params.Container.onDisconnect] * Called when the client disconnects from the Managed Hub. * Function is defined as follows: function(container) * @param {Object} [params.Container.scope] * Whenever one of the Container's callback functions is called,* references to "this" in the callback will refer to the scope* object. If no scope is provided, default is window. * @param {Function} [params.Container.log] * Optional logger function. Would be used to log to console.log* or equivalent. * @param {Object} params.IframeContainer.parent * DOM element that is to be parent of iframe * @param {String} params.IframeContainer.uri * Initial Iframe URI (Container will add parameters to this* URI) * @param {String} params.IframeContainer.tunnelURI * URI of the tunnel iframe. Must be from the same origin as the* page which instantiates the IframeContainer.


OpenAjax.hub.IframeContainer | 79

* @param {Object} [params.IframeContainer.iframeAttrs] * Attributes to add to IFRAME DOM entity. For example: * { style: { width: "100%", * height: "100%" }, * className: "some_class" } * @param {Number} [params.IframeContainer.timeout] * Load timeout in milliseconds. If not specified, defaults to* 15000. If the client at params.IframeContainer.uri does not* establish a connection with this container in the given time,* the onSecurityAlert callback is called with a LoadTimeout* error code. * @param {Function} [params.IframeContainer.seed] * A function that returns a string that will be used to seed the * pseudo-random number generator, which is used to create the* security tokens. An implementation of IframeContainer may* choose to ignore this value. * @param {Number} [params.IframeContainer.tokenLength] * Length of the security tokens used when transmitting* messages. If not specified, defaults to 6. An* implementation of IframeContainer may choose to ignore this* value. * * @throws {OpenAjax.hub.Error.BadParameters} if required params* are not present or null * @throws {OpenAjax.hub.Error.Duplicate} if a Container with* this clientID already exists in the given Managed Hub * @throws {OpenAjax.hub.Error.Disconnected} if hub is not* connected */OpenAjax.hub.IframeContainer = function( hub, clientID, params ) {}

The tunnel iframe mentioned above typically is a file that is included within an implementation of the Hub. The tunnel iframe usually is part of Hub's implementation of secure messaging.

IframeContainer detects when its iframe is navigated, as this is equivalent to a disconnect. As part of the detection system, the IframeHubClient inside the iframe window itself creates an iframe, which is called a tunnel iframe. The params.IframeContainer.tunnelURI parameter specifies the initial URL for the tunnel iframe in the same way that the params.IframeContainer.uri parameter specifies the initial URL of the container iframe. In both cases, these initial URLs are modified by the Hub, which adds tokens and FIM (Fragment Identifier Messaging) messages to the URLs.

The tunnel iframe URI MUST have the same origin as the manager application URI.

In some cases, the IframeHubClient uses the tunnel iframe to send messages back to the parent window via the tunnel's src URL.



OpenAjax.hub.IframeContainer.prototype.getIframe

/** * Get the iframe associated with this iframe container * * This function returns the iframe associated with an* IframeContainer, allowing the Manager Application to change its* size, styles, scrollbars, etc. * * CAUTION: The iframe is owned exclusively by the IframeContainer.* The Manager Application MUST NOT destroy the iframe directly.* Also, if the iframe is hidden and disconnected, the Manager* Application SHOULD NOT attempt to make it visible. The Container* SHOULD automatically hide the iframe when it is disconnected; to* make it visible would introduce security risks. * * @returns iframeElement * @type {Object} */OpenAjax.hub.IframeContainer.getIframe = function( ) {}



OpenAjax.hub.InlineContainer | 81

OpenAjax.hub.InlineContainer

OpenAjax.hub.InlineContainer implements the OpenAjax.hub.Container interface to provide a container that places components inline within the same browser window as the manager application. As such, this container does not isolates client components into secure sandboxes.

OpenAjax.hub.InlineContainer constructor

/** * Create a new Inline Container. * @constructor * * InlineContainer implements the Container interface to provide a* container that places components within the same browser window* as the manager application. As such, this container does not* isolate client components into secure sandboxes. * * @param {OpenAjax.hub.ManagedHub} hub * Managed Hub instance to which this Container belongs * @param {String} clientID * A string ID that identifies a particular client of a Managed* Hub. Unique within the context of the ManagedHub. * @param {Object} params * Parameters used to instantiate the InlineContainer. * Once the constructor is called, the params object belongs* exclusively to the InlineContainer. The caller MUST not* modify it. The following are the pre-defined properties on* params: * @param {Function} params.Container.onSecurityAlert * Called when an attempted security breach is thwarted. * Function is defined as follows: function(container,* securityAlert) @param {Function}* [params.Container.onConnect] * Called when the client connects to the Managed Hub. Function* is defined as follows: function(container) * @param {Function} [params.Container.onDisconnect] * Called when the client disconnects from the Managed Hub. * Function is defined as follows: function(container) * @param {Object} [params.Container.scope] * Whenever one of the Container's callback functions is called,* references to "this" in the callback will refer to the scope* object. If no scope is provided, default is window. * @param {Function} [params.Container.log] * Optional logger function. Would be used to log to console.log* or equivalent. * * @throws {OpenAjax.hub.Error.BadParameters} if required params* are not present or null * @throws {OpenAjax.hub.Error.Duplicate} if a Container with* this clientID already exists in the given Managed Hub * @throws {OpenAjax.hub.Error.Disconnected} if ManagedHub is not



* connected */OpenAjax.hub.InlineContainer = function( hub, clientID, params ) {}



OpenAjax.hub.HubClient | 83

OpenAjax.hub.HubClient

Interface OpenAjax.hub.HubClient extends OpenAjax.hub.Hub and provides client-side APIs (i.e., component-side APIs) to interact with the Managed Hub. Each HubClient implementation is specific to a particular implementation of OpenAjax.hub.Container.

OpenAjax.hub.HubClient constructor

/** * Create a new HubClient. All HubClient constructors MUST have* this signature. * @constructor * * @param {Object} params * Parameters used to instantiate the HubClient. * Once the constructor is called, the params object belongs to* the HubClient. The caller MUST not modify it. * Implementations of HubClient may specify additional* properties for the params object, besides those identified* below. * * @param {Function} params.HubClient.onSecurityAlert * Called when an attempted security breach is thwarted * @param {Object} [params.HubClient.scope] * Whenever one of the HubClient's callback functions is* called, references to "this" in the callback will refer to* the scope object. If not provided, the default is window. * @param {Function} [params.HubClient.log] * Optional logger function. Would be used to log to* console.log or equivalent. * * @throws {OpenAjax.hub.Error.BadParameters} if any of the* required parameters is missing, or if a parameter value is* invalid in some way. */OpenAjax.hub.HubClient = function( params ) {}

A HubClient instance makes use of the params properties throughout its lifetime, and NOT just before the constructor returns. For example, the onSecurityAlert function is invoked whenever the HubClient instance prevents an attempted security breach, even if this happens long after the constructor returns.

OpenAjax.hub.HubClient.prototype.connect

/** * Requests a connection to the ManagedHub, via the Container * associated with this HubClient.



* * If the Container accepts the connection request, the HubClient's * state is set to CONNECTED and the HubClient invokes the * onComplete callback function. * * If the Container refuses the connection request, the HubClient * invokes the onComplete callback function with an error code. * The error code might, for example, indicate that the Container * is being destroyed. * * In most implementations, this function operates asynchronously, * so the onComplete callback function is the only reliable way to * determine when this function completes and whether it has* succeeded or failed. * * A component within a Container application may call* HubClient.disconnect and then call HubClient.connect. * * @param {Function} [onComplete] * Callback function to call when this operation completes. * @param {Object} [scope] * When the onComplete function is invoked, the JavaScript* "this" keyword refers to this scope object. * If no scope is provided, default is window. * * @throws {OpenAjax.hub.Error.Duplicate} if the HubClient is* already connected */OpenAjax.hub.HubClient.prototype.connect = function( onComplete, scope ) {}


OpenAjax.hub.HubClient.prototype.disconnect

/** * Disconnect from the ManagedHub * * Disconnect immediately: * * 1. Sets the HubClient's state to DISCONNECTED. * 2. Causes the HubClient to send a Disconnect request to the * associated Container. * 3. Ensures that the client application will receive no more * onData or onComplete callbacks associated with this * connection, except for the disconnect function's own * onComplete callback. * 4. Automatically destroys all of the HubClient's subscriptions. * * This function operates asynchronously, * so the onComplete callback function is the only reliable way to * determine when this function completes and whether it has* succeeded or failed.


OpenAjax.hub.HubClient | 85

* * A client application is allowed to call HubClient.disconnect and * then call HubClient.connect. * * @param {Function} [onComplete] * Callback function to call when this operation completes. * @param {Object} [scope] * When the onComplete function is invoked, the JavaScript* "this" keyword refers to the scope object. * If no scope is provided, default is window. * * @throws {OpenAjax.hub.Error.Disconnected} if the HubClient is* already disconnected */OpenAjax.hub.HubClient.prototype.disconnect = function( onComplete, scope ) {}


OpenAjax.hub.HubClient.prototype.getPartnerOrigin

/** * If DISCONNECTED: Returns null * If CONNECTED: Returns the origin associated with the window* containing the Container associated with this * HubClient instance. The origin has the format * * [protocol]://[host] * * where: * * [protocol] is "http" or "https" * [host] is the hostname of the partner page. * * @returns Partner's origin * @type {String} */OpenAjax.hub.HubClient.prototype.getPartnerOrigin = function() {}

All of the major web browsers prevent script running in a window from accessing the DOM/script of a window whose "origin" is different. This is an instance of the Same Origin Policy. All of the major browsers prevent access if the two windows have different protocols or hosts.

Some major browsers also prevent access if the two windows have different ports, but some do not. Others may allow large port numbers to wrap around in same origin checks.



In the interest of consistency, this function returns the "lowest common denominator" origin, i.e. "[protocol]://[host]". Two windows that have the same protocol and host but different ports will appear to share the same origin.

Example origins:

"http://www.openajax.org""https://mashexample.example.co.uk"

If the HubClient and Container are in the same window (InlineHubClient) then the origin of the HubClient's partner is the origin of that window. If the client is in an iframe (IframeHubClient) then the origin of the HubClient's partner is the origin of the window associated with the ManagedHub that controls the Container.

OpenAjax.hub.HubClient.prototype.getClientID

/** * Returns the client ID of this HubClient * * @returns clientID * @type {String} */OpenAjax.hub.HubClient.prototype.getClientID = function() {}



OpenAjax.hub.IframeHubClient | 87

OpenAjax.hub.IframeHubClient

Class OpenAjax.hub.IframeHubClient implements OpenAjax.hub.HubClient for an IframeContainer and provides client-side APIs (i.e., component-side APIs) to interact with the Managed Hub..

OpenAjax.hub.IframeHubClient constructor

/*** Create a new IframeHubClient.* @constructor** @param {Object} params* Once the constructor is called, the params object belongs to* the HubClient. The caller MUST not modify it.* The following are the pre-defined properties on params:* @param {Function} params.HubClient.onSecurityAlert* Called when an attempted security breach is thwarted* @param {Object} [params.HubClient.scope]* Whenever one of the HubClient's callback functions is* called, references to "this" in the callback will refer to* the scope object. If not provided, the default is window.* @param {Function} [params.HubClient.log]* Optional logger function. Would be used to log to* console.log or equivalent.* @param {Function} [params.IframeHubClient.seed]* A function that returns a string that will be used to seed* the pseudo-random number generator, which is used to create* the security tokens. An implementation of IframeHubClient* may choose to ignore this value.* @param {Number} [params.IframeHubClient.tokenLength]* Length of the security tokens used when transmitting* messages. If not specified, defaults to 6. An* implementation of IframeHubClient may choose to ignore this* value.* @param {Object} [params.PageBus]* PageBus specific configuration for HubClient instance* @param {PageBus.policy.HubPolicy} [params.PageBus.policy]* Security policy object. This object implements onPublish* and onSubscribe functions.* @param {Function} [params.PageBus.log]* Logger callback function** @throws {OpenAjax.hub.Error.BadParameters} if any of the* required parameters is missing, or if a parameter value* is invalid in some way.*/OpenAjax.hub.IframeHubClient = function( params ) {}




OpenAjax.hub.InlineHubClient

Class OpenAjax.hub.InlineHubClient implements OpenAjax.hub.HubClient for an InlineContainer and provides client-side APIs (i.e., component-side APIs) to interact with the Managed Hub.

The following functions of InlineHubClient typically are SYNCHRONOUS:

• connect

• disconnect

• subscribe

• unsubscribe

This means that for all of these functions, the associated onComplete callbacks - and any other callbacks, e.g. Container.onSubscribe - typically are invoked BEFORE these functions return. Developers are cautioned that in most implementations of HubClient, onComplete is invoked after this function returns.

In addition, InlineHubClient.publish typically is SYNCHRONOUS. This means that the Container's onPublish and the publish function's onData callbacks typically are invoked before the publish call returns. Developers are cautioned that in most implementations of HubClient, onData is invoked after this function returns.

OpenAjax.hub.InlineHubClient constructor

/** * Create a new InlineHubClient. * @constructor * * @param {Object} params * Parameters used to instantiate the HubClient. * Once the constructor is called, the params object belongs * to the HubClient. The caller MUST not modify it. * The following are the pre-defined properties on params: * @param {Function} params.HubClient.onSecurityAlert * Called when an attempted security breach is thwarted * @param {Object} [params.HubClient.scope] * Whenever one of the HubClient's callback functions is* called, references to "this" in the callback will refer to* the scope object. If not provided, the default is window. * @param {Function} [params.HubClient.log] * Optional logger function. Would be used to log to* console.log or equivalent. * @param {OpenAjax.hub.InlineContainer}params.InlineHubClient.container * Specifies the InlineContainer to which this HubClient will* connect.* @param {Object} [params.PageBus]* PageBus specific configuration for HubClient instance


OpenAjax.hub.InlineHubClient | 89

* @param {PageBus.policy.HubPolicy} [params.PageBus.policy]* Security policy object. This object implements onPublish* and onSubscribe functions.* @param {Function} [params.PageBus.log]* Logger callback function* * @throws {OpenAjax.hub.Error.BadParameters} if any of the* required parameters are missing */OpenAjax.hub.InlineHubClient= function( params ) {}





| 91

Chapter 5 PageBus HubPolicy Overview

This chapter provides an overview of the PageBus HubPolicy security manager.

Topics

• PageBus HubPolicy Overview, page 92


92 | Chapter 5 PageBus HubPolicy Overview

PageBus HubPolicy Overview

ConceptsEach origin can be trusted to access certain types of information, where types of information correspond to topic names.

TIBCO PageBus provides an off-the-shelf security manager called PageBus HubPolicy that allows applications to restrict access to topics based on the origin of the accessor.

The PageBus security manager, which is compliant with the OpenAjax Hub 2 specification, allows the application to control which components of a mash-up are allowed to publish and/or subscribe to each topic. Each time subscribe() is called, the ManagedHub consults the PageBus HubPolicy to determine whether the caller is permitted to subscribe. Each time publish() is called, the ManagedHub consults the PageBus HubPolicy to determine whether the caller is permitted to publish, and if so which subscribers are permitted to receive the published data.

In addition, TIBCO PageBus allows components restrict the mash-ups with which they are willing to exchange particular topics. Each time a component calls subscribe(), the HubClient consults the PageBus HubPolicy to determine whether the mash-up is allowed to send data to the client on the topic. Each time the component calls publish(), the HubClient consults the PageBus HubPolicy to determine whether the mash-up is allowed to receive data on this topic.

In both cases, components and mash-ups can be arbitrarily grouped by origin, and publish and subscribe permissions for various topics can be granted to each origin.

Origin

Origin is an extremely important concept in web browser security. The browser itself uses origin to restrict access to certain types of resources.

The OpenAjax Hub specification defines an origin string as a string of the form

protocol://subdomain

e.g. http://hr.portal.tibco.com or http://www.example.com. Port is not included, because some web browsers, notably Microsoft Internet Explorer®, ignore ports when enforcing the same origin policy (see below). Using only protocol and (sub-)domain makes the origin concept portable across all major web browsers.


PageBus HubPolicy Overview | 93

The "Same Origin" Policy

Every web browser implements a vital security policy called the same origin policy. This browser-enforced policy prevents script from one web site from accessing or interfering with another site, for instance by stealing cookies or tokens associated with another site or using XmlHTTPRequest to silently send requests to another site on behalf of the user. The same origin policy prevents these kinds of exploits by allowing JavaScript running on pages that originate from one web site to freely access each other's methods and properties, while preventing such script from accessing most of the methods and properties of pages from other sites. The browser’s strict enforcement of the same origin policy is absolutely critical to the security architecture of the World Wide Web.

The security architecture of TIBCO PageBus relies heavily on the browser’s enforcement of the same origin policy.

The Iframe Container implementation included in TIBCO PageBus leverages the same origin policy to isolate untrusted components in secure sandboxes. These sandboxes are implemented as iframes whose origins differ from that of the mash-up application and from those of unrelated components. This implementation employs the browser’s own strict enforcement of the same origin policy to prevent untrustworthy components from interfering with other mash-up components running in the browser.

Components May Share an Origin

In many cases, several related components and pages don’t need to be isolated from each other; they only need to be isolated from everything else. Such components often need to share cookies with each other or access the same web services.

When such components are combined within a mash-up, the mash-up will frequently associate all of these closely related components with one origin.

Access PermissionsThe PageBus HubPolicy architecture is based on the simple idea that each origin can be trusted to access certain types of information, where types of information correspond to topic names. Each origin is granted permission to publish and/or subscribe to various topics. The table below summarizes how permissions relate to trust.

Permission What it means (trustworthiness)

Origin X is allowed to publish to topic T

Origin X is a trustworthy source of the type of information associated with T



By focusing our permissions model on the relationship between origin and information, we keep permissions management both simple and flexible, even if the numbers of potential topics, publishers, subscribers and intermediaries (such as mash-ups) increase rapidly.

For example, suppose that we have the following sets of components:

• 5 sales force automation widgets from a SaaS vendor, which can share one origin because they are all trusted with the same information. These components can publish and subscribe on com.example.sales.foo.bar.* and can publish on com.example.geo.location.select and com.example.geo.route.select

• 3 custom sales force automation widgets that must be isolated from the other 5 because they provide access to very sensitive information to which the SaaS widgets should not have access. These components can publish and subscribe on com.example.sales.foo.bar.* and com.example.sales.very.secret.info.*

• 10 benefits management widgets from the HR department, built by IT, which provide access to a user’s very personal information. These components can publish and subscribe to topics within the topic set defined by com.example.hr.benefits.*.*.*

• 2 map widgets provided by a public web site. These subscribe to com.example.geo.route.select and com.example.geo.location.select

• A HR mash-up containing the HR widgets

• A sales force automation mash-up containing the sales force and map widgets.

In this example, there are 20 widgets, 2 mash-ups and 5 groups of topics. There are only 5-7 origins. We grant publish and subscribe permissions that allow each origin to access specific topics. We do not attempt to micromanage the permissions of every individual component (which would be futile in any case); the same origin policy only prevents access between origins, so components that share an origin may be able to interfere with each other.. As a result, whoever sets up the access permissions for this set of components and mash-ups only needs to define a small number of publish and subscribe access policies, and does not need change these policies every time someone wants to use the existing widgets in new combinations.

Origin Y is allowed to subscribe to topic T

Origin Y can be trusted to securely handle the type of information associated with T

Permission What it means (trustworthiness)



Granting and Revoking PermissionA PageBus HubPolicy instance has a grant() operation for granting publish and subscribe privileges to origins and a revoke() operation for revoking these privileges.

When a ManagedHub is created, the manager application can specify a HubPolicy that this ManagedHub is to use as its security manager. The HubPolicy object may contain pre-loaded privileges privileges that determine which container origins the ManagedHub will trust with each type of event. Privileges can also be granted and revoked later on.

If a policy is not specified during ManagedHub creation, the manager application must manage container access permissions using its own security manager

When a HubClient is created, the component or sandbox infrastructure can specify a HubPolicy that this HubClient is to use as its security manager. The HubPolicy object may contain pre-loaded privileges that determine which manager applications the HubClient will trust. Privileges can also be granted and revoked later on.

If a policy is not specified during HubClient creation, the HubClient trusts all manager applications.

Granting Permission to Wildcard Topics

When an application grants a component or manager permission to "publish on a wildcard topic," this means that the publisher can publish on any non-wildcard topic that matches the wildcard. It is illegal to publish on wildcard topics.

When an application grants a component or manager permission to subscribe to a wildcard topic, this means that the publisher can subscribe to any wildcard or non-wildcard topic that matches the specified wildcard. For example, if an application grants the origin associated with a component permission to subscribe to “**”, then the component can subscribe to any topic.

Enforcing PermissionsThe following figure shows how PageBus checks and enforces access permissions when a component publishes an event.



Figure 12 Permission Checks and Enforcement within ManagedHub and HubClient

Figure 12 shows that in order for data to flow on topic T from one component to another:

• The first component must trust the mash-up origin to receive data on topic T

• The mash-up must trust the first component to publish on topic T

• The mash-up must trust the second component to subscribe to topic T

• The second component must trust the mash-up to send (publish) data on topic T

This would be accomplished as follows:

• Using the first client’s HubPolicy, which manages permissions for potential mash-ups:

policy.grant( OriginM, “s”, theTopic );

• Using the ManagedHub’s HubPolicy, which manages permissions for containers:

policy.grant( OriginA, “p”, theTopic );

• Using the ManagedHub’s HubPolicy, which manages permissions for containers:

policy.grant( OriginM, “s”, theTopic );

The origin is OriginM because the second component is an inline component whose origin is M, just like the manager application.



• Using the second client’s HubPolicy, which manages permissions for potential mash-ups:

policy.grant( OriginM, “p”, theTopic );

Several simplifications are possible:

• Use wildcard topics to grant permissions to many topics at once.

• If components don’t need to enforce permissions on potential mash-ups, you can disable client-side permissions entirely by not specifying a HubPolicy for the HubClient.

The figure also shows the checks that are performed when the second component subscribes. At that time, only checks #3 and (possibly) #4 are carried out.

Permissions are Dynamic

TIBCO PageBus allows each application to decide how to obtain permission information. It does not require a particular web service or persistence format. Rather, each application can obtain permissions from some source and then call the PageBus HubPolicy’s grant function to grant permission to topics and origins.

Permissions can be granted and revoked at any time; each change takes effect immediately, as follows:

• If a publisher’s permission to publish is revoked, then the ManagedHub will discard events published by this publisher until permission is re-granted.

• If a subscriber with an existing subscription loses the right to subscribe, then the ManagedHub will stop forwarding events to that subscriber until permission is re-granted.

OpenAjax Hub Security Manager

The PageBus HubPolicy implements the OpenAjax Hub security manager mechanism, which consist of two callback functions that are invoked by the ManagedHub:

• onPublish is called whenever a component publishes

• onSubscribe is called whenever a component subscribes

The PageBus HubPolicy implements these callback functions and the ManagedHub invokes them at the appropriate times.



The OpenAjax Hub specification does not define corresponding security checks within HubClient. TIBCO PageBus provides this functionality in order to help developers implement secure widgets. The feature, which runs within the HubClient, uses HubClient.getPartnerOrigin() to indentify the origin of the page that contains the HubClient. Depending on the origin of the page, this feature decides whether to allow or forbid the component to exchange events with the containing page.

Using PageBus HubPolicy

Initialization

A HubPolicy is an instance of PageBus.policy.HubPolicy. To create a HubPolicy instance, simply use the constructor. To use a HubPolicy to secure a ManagedHub, add the optional PageBus property to the params parameter in the ManagedHub constructor, as shown below.

var params = { /* log: console.log */ };var pol = new PageBus.policy.HubPolicy( params );

var managedHub = new OpenAjax.hub.ManagedHub({

onPublish: function() { return true; },onSubscribe: function() { return true; },onSecurityAlert: mySecurityAlertFunction,PageBus: {

policy: pol}

});

Granting Privileges

To tell a HubPolicy instance to grant publish and subscribe privileges to an origin, use the grant() function.

var S = PageBus.policy.Ops.Subscribe;var P = PageBus.policy.Ops.Publish;

pol.grant( “http://xyz1.example.com”, S, “my.topic” );pol.grant( “http://xyz1.example.com”, P, “*.foo.bar” );pol.grant( “http://xyz2.example.com”, P, “my.topic” );pol.grant( “http://xyz2.example.com”, S, “**” );



In this example, the origin http://xyz1.example.com is granted the right to subscribe to the topic “my.topic” and publish to any topic that matches the wildcard “*.foo.bar” (such as “a.foo.bar” or “xyz.foo.bar”) . The origin http://xyz2.example.com is granted the right to publish to that topic and subscribe to all topics.

Revoking Privileges

To tell a HubPolicy instance to revoke an origin’s privileges, use revoke() or revokeAll(). The revoke() function revokes a specific privilege. revokeAll() revokes all priveleges associated with an origin, so that the origin is no longer allowed to publish or subscribe to anything.


pol.revoke( “http://xyz1.example.com”, S, “my.topic” );pol.revoke( “http://xyz1.example.com”, P, “*.foo.bar” );pol.revokeAll( “http://xyz2.example.com” );

Only privileges that have been explicitly granted can be revoked, and the entire grant must be revoked. If we grant origin X permission to publish on topic “a.b.**”, then we can call revoke with “a.b.**” as the topic parameter, and thereby revoke that permission. The revoke() function CANNOT revoke only a portion of the grant, such as “a.b.c”.

If two grants overlap (e.g. “a.**” overlaps “*.b.*.d” wherever the first token is “a”), the revoke() function can revoke each grant without affecting the other grant. That is, it can revoke the grant that allows publication on “a.**”, after which the grant that allows publishing on “*.b.*.d” remains.

Checking Privileges

The HubPolicy object provides two functions that can be used to check privileges. The isAllowed() function checks whether a particular operation is allowed. The listAllowed() function lists all publish or subscribe privileges belonging to the specified origin.


Boolean ok = pol.isAllowed( “http://xyz1.example.com”, S, “my.topic” );var priveleges = pol.listAllowed( “http://xyz1.example.com”, P );for( var i = 0; i < priveleges.length; i++ ) {

alert( privileges[i] );



}

Custom Security Management, Hooks and Wiring

When a ManagedHub instance is created, the manager application can specify additional policy logic within the mandatory onPublish() and onSubscribe() callback functions. This logic could perform additional security checks, “wiring” logic and/or provide troubleshooting tools. These functions will be called AFTER the PageBus HubPolicy’s own onPublish and onSubscribe hooks, if the HubPolicy's hooks return true. Custom logic MUST return true if the publish or subscribe operation should continue, and false if the publish or subscribe operation should be blocked.

If you wish to use your custom security manager functions INSTEAD OF the PageBus HubPolicy, do not specify a PageBus.policy property when you use the ManagedHub constructor. PageBus HubPolicy is a completely optional component.

If you wish not to perform security management within the HubClient, do not specify a PageBus.policy property when you use the HubClient constructor to instantiate a HubClient instance.

The OpenAjax Hub specification does not provide any means to add custom security manager callbacks to HubClient instances, so you cannot perform custom security management on the client side.

Security and Caching

The PageBus security manager enforces access permissions in PageBus Event Cache scenarios as well as in ordinary publish/subscribe scenarios. Please see the PageBus Event Cache chapter for more details.


| 101

Chapter 6 PageBus HubPolicy Reference

This chapter describes the TIBCO PageBus HubPolicy APIs.

Topics

• PageBus.policy.Ops, page 102

• PageBus.policy.HubPolicy.grant, page 103

• PageBus.policy.HubPolicy.revoke, page 104

• PageBus.policy.HubPolicy.revokeAll, page 105

• PageBus.policy.HubPolicy.isAllowed, page 106

• PageBus.policy.HubPolicy.listAllowed, page 107

• PageBus.policy.HubPolicy.onPublish, page 108

• PageBus.policy.HubPolicy.onSubscribe, page 109


102 | Chapter 6 PageBus HubPolicy Reference

PageBus.policy.OpsConstants

Description PageBus.policy.Ops contains a set of constants that specify operation codes used as parameters by the grant() and revoke() functions. The values of the operation codes are as follows:

PageBus.policy.Ops.Publish "p"

PageBus.policy.Ops.Subscribe "s"


PageBus.policy.HubPolicy.grant | 103

PageBus.policy.HubPolicy.grantFunction

Description The grant() operation grants a privilege to the specified origin.

When the HubPolicy is used by a ManagedHub instance, this privilege allows all components associated with the specified origin to perform the specified operation on the specified topic.

When the HubPolicy is used by a HubClient instance, this privilege determines what the HubClient will allow the mash-up application containing it to do.

The topic may be a wildcard.

Returns null

Parameters

Throws

Remarks Can be safely called from within PageBus callback function.


origin string Origin to which permission is being granted. Origin string format is "protocol://domain"

operation PageBus.policy.Ops.Publish, PageBus.policy.Ops.Subscribe

Operation for which permission is being granted

topic string Topic (may be wildcard) for which permission is being granted

OpenAjax.hub.BadParameters An illegal topic was specified



PageBus.policy.HubPolicy.revokeFunction

Description The revoke() operation revokes a privilege that had been explicitly granted to the specified origin.

When grant() is used to grant a privilege, revoke() can only be used to revoke the entire privilege. revoke() cannot be used to revoke part of a grant. That is, the revoke() call in the following example will revoke the grant:

pol.grant( originX, PageBus.policy.Ops.Publish, “a.b.*.c.**” );pol.revoke( originX, PageBus.policy.Ops.Publish, “a.b.*.c.**” );

On the other hand, the revoke() call in the following example will have no effect.

pol.grant( originX, PageBus.policy.Ops.Publish, “a.b.*.c.**” );pol.revoke( originX, PageBus.policy.Ops.Publish, “a.b.*.c.d.*” );

Returns null

Parameters

Throws



origin String Origin. Origin string format is "protocol://domain"


Operation

topic String Topic. May be a wildcard topic.

OpenAjax.hub.BadParameters An illegal topic was specified


PageBus.policy.HubPolicy.revokeAll | 105

PageBus.policy.HubPolicy.revokeAllFunction

Description The revokeAll() operation revokes all privileges that have been granted to the specified origin

Returns null

Parameters



origin origin Origin. Origin string format is “protocol://domain”



PageBus.policy.HubPolicy.isAllowedFunction

Description isAllowed() returns true if the specified origin is allowed to perform the specified operation on the specified topic. Otherwise it returns false.

The origin is allowed to perform the operation if the topic parameter matches the topic specified in any privilege that has been granted. For example, if grant has been called on the topic “a.b.*” and grant has been called on the topic “x.y.z”, then isAllowed() will return true if the topic parameter matches either “a.b.*” or “x.y.z”. Thus, if “a.b.c”, “a.b.Mnopqrs” or “x.y.z” is specified, then isAllowed() returns true. If “m.n.o.p” is specified, isAllowed() returns false.

Returns Boolean

Parameters

Remarks Can be safely called from within a PageBus callback function.




Operation

topic String Topic. May be a wildcard topic.


PageBus.policy.HubPolicy.listAllowed | 107

PageBus.policy.HubPolicy.listAllowedFunction

Description listAllowed() returns an array of topics on which the specified origin has been granted the privilege to perform the specified operation.

Returns Boolean

Parameters

Remarks Can be safely called from within a PageBus callback function.




Operation



PageBus.policy.HubPolicy.onPublishFunction

Description This is the OpenAjax.hub.ManagedHub onPublish callback function (See OpenAjax.hub.ManagedHub onPublish callback function on page 64 for more information on this function). It returns true if:

• the origin associated with pcont has the right to publish on topic

• the origin associated with scont has the right to receive the event (because scont has permission to subscribe to topic)

Returns Boolean


topic String Topic string on which a message is being published

data any The message that is being published

pcont OpenAjax.hub.Container Container that is publishing

scont OpenAjax.hub.Container Container that is being checked to see whether it can receive the published event


PageBus.policy.HubPolicy.onSubscribe | 109

PageBus.policy.HubPolicy.onSubscribeFunction

Description This is the OpenAjax.hub.ManagedHub onSubscribe callback function (See that section). It returns true if:

• the origin associated with cont has the right to subscribe to topic

Returns Boolean


topic string Topic string on which a message is being published

cont OpenAjax.hub.Container Container that is being checked to see whether it can subscribe to topic




| 111

Chapter 7 The PageBus Event Cache

The PageBus Event Cache helps components to synchronize shared properties, even if one component sets a value before the consumer of the value subscribe to the update event. It allows the Managed Hub to cache published events so that subscribers that are created afterward can receive them.

Topics


• PageBus Event Cache Function Reference, page 116

• The PageBus Sub-Object, page 117

• Hub.pagebus.query, page 118

• Hub.pagebus.store, page 119


112 | Chapter 7 The PageBus Event Cache

Overview

TIBCO PageBus provides an event cache for each hub instance. The event cache helps components to synchronize shared properties, even if one component sets a value before the consumer of the value subscribes to the update-value event.

The event cache stores copies of published events and delivers these events to subscribers that are created afterward. Components can also query the cache to retrieve stored values.

The application can specify which topics participate in the event cache and which subscriptions need to be initialized with cached events. A topic for which caching is enabled is called a cache-enabled topic. A subscription that is to receive cached events is called a cache-enabled subscription.

Each ManagedHub instance contains a “master” cache and each participating HubClient instance contains a “slave” cache. Each component can specify which topics its HubClient caches; the HubClient’s cache contains only these topics. The ManagedHub’s cache contains all of the topics that are cached by its HubClients; in addition, the ManagedHub’s cache contains any topics that the manager application itself has cache-enabled, even if no HubClient is interested in these topics yet.

Updates to the ManagedHub’s cache are automatically propagated to HubClients.

How Cache Entries Are ManagedA topic is said to be cache-enabled within a hub instance if one or more cache-enabled subscriptions matches that topic.

When a topic is cache-enabled, the hub's event cache maintains at most one cache entry for that topic. A cache entry is only created for a topic when an event is published on that topic. As events are published on that topic, they are cached in the topic's cache entry.

If multiple cache-enabled subscriptions match a single topic, a single cache entry is created for that topic. This cache entry keeps track of the cache-enabled subscriptions that match its topic. When the last cache-enabled subscription that matches the topic is destroyed, the event cache automatically deletes the cache entry.


Overview | 113

Example

Suppose that an application creates a cache-enabled subscription to "a.b.**". This cache-enables all topics that match "a.b.**". Suppose that the application also creates a cache-enabled subscription to "a.*.c". This cache-enables all topics that match "a.*.c".

The topic "a.b.c" is now cache-enabled for 2 reasons:

1. Because of the subscription to "a.b.**"

2. Because of the subscription to "a.*.c"

The topic "a.b.c.d.e" is cache-enabled for one reason: it matches "a.b.**".

If an event (event1) is published on "a.b.c", a SINGLE copy of the event is inserted into the hub's cache, under the topic "a.b.c".

If an event (event2) is now published on "a.b.c.d.e", a single copy of the event is inserted into the hub's cache, under the topic "a.b.c.d.e".

Now the cache contains 2 entries:

"a.b.c": event1"a.b.c.d.e": event2

Suppose that after publishing these events, I unsubscribe from "a.b.**" but keep my subscription to "a.*.c". When the cache-enabled subscription to "a.b.**" is destroyed, the topic "a.b.c.d.e" is no longer cache-enabled. The event cache automatically deletes the cache entry for "a.b.c.d.e".

Because the cache-enabled subscription to "a.*.c" still exists, the topic "a.b.c" is still cache-enabled.

So the cache now contains 1 entry:

"a.b.c": event1

If I now unsubscribe from "a.*.c", the topic "a.b.c" is no longer cache-enabled. The event cache automatically deletes the cache entry for "a.b.c". The cache now contains zero entries.

Cache-Enabled SubscriptionsA component or manager creates a cache-enabled subscription by calling Hub.subscribe() with a subscriberData object in which the property PageBus.cache is set to true. For example:

// Manager Application creates a cached subscription, and thereby// creates a cache on the topic “my.topic” if none existed already:var mh = new OpenAjax.hub.ManagedHub( … );mh.subscribe(“my.topic”, myOnData, myScope, myOnComplete,



{ foo: “bar”, PageBus: { cache: true } });

After a cache-enabled subscription is created, TIBCO PageBus calls the subscription’s onData callback zero or more times to deliver all cached events that match the subscription’s topic. Once these cached events have been delivered, the cache-enabled subscription behaves exactly the same as any other subscription.

A cache-enabled subscription is destroyed by calling unsubscribe or by disconnecting, as with any other subscription.

Storing Data in the CacheTo store a data value in the cache, a component or manager application simply publishes on a cache-enabled topic. When this happens, the cache makes a “deep copy” of the message and stores the copy under the publish topic.

As in all Managed Hub scenarios, published messages must be JSON serializable, because the data is converted into a JSON string for delivery across origin boundaries.

The publish() function works regardless of whether the topic is cached. If there is a cache, data is copied, cached, and then published; if not, the data is simply published. PageBus also provides a store() function that does check whether a cache exists before publishing, and only publishes if the cache exists. If there is no cache on the specified topic, store throws an exception rather than publishing.

Querying the CacheA component or manager application can query the cache using the query() function. The query operation for ManagedHub returns an array containing all events in the local cache (the HubClient or ManagedHub cache instance, depending on whether the caller is a component or the manager application) whose topics match the specified query.

The following example shows how a client can query the cache.

// hc is a HubClient instancevar res = hc.pagebus.query( “com.example.foo.bar.**” );for( var r = 0; r < res.length; r++ ) {

// Each result contains a topic and a value:alert( res[r].topic + “: “ + res[r].value );

}


Overview | 115

Enabling CachingA component or manager application enables caching for a topic simply by creating a cache-enabled subscriber. If the topic is a wildcard, it enables caching on all matching topics, including matching wildcard topics. Thus, enabling caching on the topic “a.**” enables caching on all topics beginning with “a.”, including “a.b.c”, “a.m”, “a.b.c.**” and “a.*.foo”.

Disabling CachingA topic T remains cache-enabled as long as there is at least one cache-enabled subscription whose topic matches T. When the last such subscription is destroyed, T is no longer cache-enabled and its cached value, if any, is deleted.

Cache SecurityWhen event caching is used, TIBCO PageBus enforces the same security policies that it enforces for ordinary publish-subscribe traffic.

The ManagedHub enforces the usual security policies:

• The ManagedHub only allows a component to update the master cache via publish() or store() if the component’s origin has permission to publish to the specified topic.

• The ManagedHub only allows a component to create a cache-enabled subscription if the component’s origin has permission to subscribe to the specified topic.

• If a component subscribes to a topic, and its origin’s “subscribe” permission is then dynamically revoked, the ManagedHub stops replicating cached data to the component’s HubClient.

If the HubClient has an associated HubPolicy, then the HubClient also enforces the usual security policies:

• The HubClient only allows the component to request the creation of a cache-enabled subscription if the origin of the manager application has permission to publish to the topic.

• The HubClient only allows the ManagedHub to push updates to the HubClient cache if the origin of the manager application has permission to publish to the topic.

• The HubClient only allows the client’s publish or store to send data to the ManagedHub if the manager application has permission to subscribe to the topic.



PageBus Event Cache Function Reference

The remaining sections of this chapter describe the PageBus Event Cache functions.


The PageBus Sub-Object | 117

The PageBus Sub-Object

TIBCO PageBus adds a pagebus sub-object to each Hub (Managed Hub, HubClient) instance. The pagebus object implements the event cache functions:

• query query the cache to obtain an array of matching events

• store if the specified topic is cache-enabled, use publish to store a value in the cache



Hub.pagebus.queryFunction

Description Query the local copy of the cache and return an array containing the results. Each result represents an event, and contains the event’s topic and message value.

When a wildcard topic is specified, the results array contains zero or more results. When a non-wildcard topic is specified, the results array contains either zero results or one result.

Within each result, the topic is the topic on which the event was published, rather than the topic specified in the query. The two will differ when the query topic is a wildcard topic.

Returns Array of objects

The array contains the results of the query. Each result in the array is an object of the form

{ topic: “publishTopic”, value: copyOfPublishedValue }

The order of the results in the array is arbitrary.

Returned results are READ-ONLY and MUST NOT be modified.

Parameters

Throws

Remarks All PageBus functions can be safely called from within PageBus callback functions.


topic string Topic name on which to publish the message. This MAY be a wildcard topic.

OpenAjax.hub.BadParameters An invalid topic was specified.


Hub.pagebus.store | 119

Hub.pagebus.storeFunction

Description If the topic appears in the local cache, then publish the value on that topic. This both updates the topic’s cache by storing a copy of the published value, and keeps other cache instances in sync with this one.

Returns null

Parameters

Throws

Remarks The store function automatically makes a copy of the message value and stores the copy in the cache. This is a "deep copy," meaning that if the value contains nested sub-objects or arrays, these too are copied. Message values must therefore be copyable. Message values must therefore consist of the following types:

• null


• String

• Number

• Object (a JavaScript object, e.g., { foo: 7, bar: { baz: [“x”, “y”] } } )

• Array

Data values must NOT include functions, Date objects, web browser objects, or other values that cannot be deep-copied or other values that are not included in the list of supported types.

All PageBus functions can be safely called from within PageBus onData/onComplete callback functions.


topic string Topic name on which to publish the message. This MUST NOT be a wildcard topic.

message any (see below) Message content. This data value MUST be serializable as JSON.

PageBus.cache.Error.NoCache There is no cache for this topic.




| 121

Chapter 8 Best Practices and FAQs

This chapter provides information on best practices and troubleshooting for TIBCO PageBus.

Topics

• Callback Functions, page 122

• Event Sequence, page 123

• Security Alerts, page 124

• Disconnect and Reconnect, page 126

• Removing a Container, page 127

• Configuration Driven Construction, page 128

• Troubleshooting, page 129

• Browser-specific behavior, page 131


122 | Chapter 8 Best Practices and FAQs

Callback Functions

No ExceptionsCallback functions such as the onData callback for subscribe() should never throw exceptions. They should catch their own errors and handle them within the callbacks themselves.

If a callback does throw an exception, TIBCO PageBus will swallow the exception. During development and debugging, TIBCO PageBus can be configured to log errors and you can also enable a debugger breakpoint. See the section on Troubleshooting, below.

Synchronous or Asynchronous?Application code should generally be written so that it works properly regardless of whether HubClient onData and onComplete callback functions, as well as HubClient subscribe, unsubscribe, publish, connect and disconnect functions, are synchronous or asynchronous. InlineHubClient functions are synchronous and blocking; IframeHubClient functions are typically asynchronous and non-blocking, but may (depending on the implementation of postMessage in the browser) behave synchronously in some situations.

Return QuicklyCallback functions should return quickly if possible, rather than performing long, synchronous activities. JavaScript within a page is single-threaded.


Event Sequence | 123

Event Sequence

When a single event is published, the order in which subscribers’ onData callback functions are invoked is arbitrary and unpredictable.

If an onData callback publishes a second event, subscribers who receive both events will always process the first event before they receive the second event (FIFO order).

If two different events are published simultaneously by components in different Iframe Containers, the order in which a subscriber will receive the two events is arbitrary.



Security Alerts

Frame PhishingBecause an IframeHubClient uses iframes, there is a possibility that some malicious ancestor frame could illicitly try to replace the page in the iframe with a phishing page that impersonates it.

The OpenAjax Hub implementation therefore includes logic that detects and blocks frame phishing attacks against IframeContainer instances. It does this by detecting unexpected unloads of the iframe window.

When the IframeContainer detects that the window has unloaded, it raises a security alert of type FramePhish by calling the onSecurityAlert callback function registered by the manager application. When such an alert is raised, the manager application could:

• destroy the Container and replace it with an inline warning message OR

• wait for a few seconds for the HubClient to reconnect to the Container, which would happen if the iframe’s window unload was a refresh or some other legitimate (and brief) interruption of activities rather than a frame phishing attack.

Other behavior is also possible. Care should be taken, however, to avoid opening security holes.

Load Timeout and ForgedMessageIf a frame phishing attack is launched before the contents of the iframe can initialize, then either

• the load timer for the IframeContainer will expire and the Container will raise a LoadTimeout security alert by calling the manager application’s onSecurityAlert callback function, OR

• the phishing frame will attempt to connect to the IframeContainer, will be discovered to be fraudulent, and will thus cause the IframeContainer to raise a ForgedMessage security alert

A ForgedMessage alert indicates that a component or mash-up is trying to impersonate another component/mash-up. The Hub implementation can detect this.


Security Alerts | 125

A LoadTimeout may be caused by an attack, but it could also be caused by a very slow server, or a component that does not call HubClient.connect in a timely way. To avoid the latter problem, a component within a Container should call connect() as soon as possible after initializing.



Disconnect and Reconnect

Once an Iframe HubClient disconnects from the Iframe Container, the Iframe Container is no longer able to detect frame phishing attacks on the iframe. When an Iframe HubClient disconnects from its Iframe Container, the manager application should immediately take action to prevent the user from being tricked by a frame phishing attack. For example:

• Destroy the Iframe Container, or,

• Hide the iframe, start a timer and display a message indicating that the Container is “reloading.” If the component in the iframe calls connect() and reconnects successfully, restore the iframe. If the timer expires, destroy the iframe and display an error message.

To detect the disconnect and reconnect events, register onDisconnect and onConnect callback functions with the IframeContainer. Certain TIBCO products make use of the ability of a HubClient to reconnect after disconnecting.


Removing a Container | 127

Removing a Container

A Container may be removed in one of two ways:

• Immediate

• “Polite”

If a Container is thought to have a security problem, remove it immediately.

If Container removal does not need to be instantaneous, the Container should probably be removed in a “polite” manner that allows the component hosted in the Container to clean up any state (e.g. tear down an Ajax Comet connection, log off of a server, etc.) before being destroyed. To accomplish this kind of “polite” removal, the manager application may send the component some kind of application-level message (called a shutdown message) indicating that the component should clean itself up and disconnect. When the component has finished cleaning up its own state, the component should call disconnect(). The manager application should listen for this disconnect by registering an onDisconnect callback with the Container, and should respond to the disconnect by calling removeContainer().



Configuration Driven Construction

Applications will often change the parameters associated with Containers, HubClients, ManagedHubs and Policy objects over time (e.g. turning logging on and off, modifying load timeouts, etc.). Rather than burying the values of these parameters in your code, it is a good idea to externalize them as configuration objects and to use factory functions to create the actual objects.

We recommend this approach, which is a variant of the dependency injection design pattern.


Troubleshooting | 129

Troubleshooting

Various tools are available to help troubleshoot problems.

DebuggerTIBCO PageBus provides built-in breakpoints when callbacks throw exceptions. These are normally disabled. To enable them:

• To enable TIBCO PageBus Policy and Cache breakpoints, add the following function to your code after loading TIBCO PageBus in the manager application:

PageBus._debug() { debugger; }

This will enable debugging throughout manager and containers.

• To enable OpenAjax Hub breakpoints, set the following value in your code:

OpenAjax.hub.enableDebug = true

LoggingTIBCO PageBus provides built-in logging to a logger function of your choice (e.g. console.log).

To enable logging in OpenAjax ManagedHub, add a log parameter to the ManagedHub constructor. The value of the parameter should be a log function. For example:

var mh = OpenAjax.hub.ManagedHub( { …, log: console.log } );

To enable logging in a Container or HubClient, add a log parameter to the object’s constructor. The value of the parameter should be a log function. For instance:

var ctnr = OpenAjax.hub.IframeContainer( { …, log: console.log } );

To enable logging in the HubPolicy object, add a log parameter to the params parameter of the HubPolicy constructor, e.g.:

var pol = PageBus.policy.HubPolicy( { log: console.log } );



TimeoutsWhen stepping through logic in a debugger, the OpenAjax Hub’s security timeouts will probably fire, causing security alerts and aborting the application. To prevent this, temporarily set security timeouts to very large numbers while doing debugging, Be careful to set them back to more secure values before using the Hub in a production situation!

HooksEven though TIBCO PageBus provides security management, it also allows you to add your own onPublish, onSubscribe, and onUnsubscribe functions, which could be used for monitoring traffic during troubleshooting.

PrivilegesIf data is not flowing, check the permissions of the publisher, the subscriber and any intermediary (e.g. the manager application’s page). Make sure that the publisher has permission to publish on the topic, the subscriber has permission to subscribe and the intermediaries have permission to subscribe and publish.


Browser-specific behavior | 131

Browser-specific behavior

The behavior of the IframeContainer implementation may depend on the web browser and the web browser version being used. In particular, PageBus uses postMessage to transmit data between frames if the browser supports postMessage; otherwise it uses Fragment Identifier Messaging (FIM).

The following versions of popular web browsers support postMessage:

• Apple Safari version 4 or later

• Microsoft Internet Explorer version 8 or later

• Mozilla Firefox version 3 or later

Earlier versions of these browsers do not support postMessage.

When FIM is used, the maximum permitted URL length of the browser may impact FIM performance. In particular, Microsoft Internet Explorer’s URL limit is 2,083 characters. Safari and Firefox have maximum URL lengths in excess of 80,000 characters.

When FIM is used, Microsoft Internet Explorer makes a clicking noise.




| 133

Chapter 9 Migration

This chapter explains issues that are important if you are migrating from TIBCO PageBus 1.2 or an earlier release to PageBus 2.0.

Topics

• Migration, page 134


134 | Chapter 9 Migration

Migration

PageBus version 2.0 includes a number of changes versus version 1.2. These changes are primarily driven by the move to OpenAjax Hub v2.0.

Errors TIBCO PageBus now uses the OpenAjax 2.0 exceptions.

Filters The new version of the standard Hub interface eliminates filter functions, so we have done the same throughout TIBCO PageBus.

Errors in callbacks If a callback throws an exception, we now log to the logger function and use the debugger keyword to halt execution during debugging, rather than publishing on a special topic.

In addition, we made the decision to use the standard OpenAjax terminology in this version, though this does not require any code changes:

• The term “topic” replaces the term “subject”.

We have modified the Event Cache query() operation to make it more applicable to Managed Hub scenarios. In the process, we have significantly simplified the query() function provided in the Simple PageBus API.

Documents

TIBCO PageBus Developer,Aos Guide › pub › pagebus › 2.0.0-october... · programmatic interfaces, and best practices that help you successfully build composite rich internet