TIB®/Adapter for Web™

User’s Guide
Software Release 5.1
October 2000
Important Information

The information contained in this document is subject to U.S. and international copyright laws and
treaties and all rights are reserved. No part of this document may be reproduced in any form
without the written authorization of an officer of TIBCO Software Inc.

Technologies described herein are covered by existing patents and pending patent applications.

TIBCO technology is protected under US patent number 6,003,011.

TIB, TIBCO, TIB/ActiveEnterprise and Information Bus are registered trademarks in the US and
other countries.

All brand and product names are trademarks or registered trademarks of their respective holders.

THIS PUBLICATION 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 PUBLICATION 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 PUBLICATION. TIBCO SOFTWARE INC. MAY MAKE
IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS PUBLICATION AT ANY TIME.

Printed in the USA.

Copyright © 1997-2000 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc.
READ THIS END USER LICENSE AGREEMENT
CAREFULLY. BY DOWNLOADING OR INSTALLING THE
SOFTWARE, YOU AGREE TO BE BOUND BY THIS
AGREEMENT. IF YOU DO NOT AGREE TO THESE
TERMS, DO NOT DOWNLOAD OR INSTALL THE
SOFTWARE AND RETURN IT TO THE VENDOR FROM
WHICH IT WAS PURCHASED. RETURNS BY THE
ORIGINAL PURCHASER WITHIN THIRTY (30) DAYS OF
THE PURCHASE DATE WILL RECEIVE A FULL
REFUND.
Upon acceptance, the following shall govern your use of
the Software except to the extent all or any portion of the
Software (a) is subject to a separate written agreement,
(b) includes a separate “click-on” license agreement as
part of the download or installation process, or (c) is
provided by a third party under the terms set forth in an
addenda at the end of this Agreement, in which case the
terms of such addenda shall control over inconsistent
terms with regard to such portion(s).
License Grant. The Software is the property of TIBCO or
its licensors and is protected by copyright and other laws.
While TIBCO continues to own the Software, TIBCO
hereby grants to Customer a limited, non-transferable,
non-exclusive, license to use the number of Permitted
Instances set forth in the Ordering Document, in
machine-readable, object code form and solely for
Customer’s internal business use.
Restrictions. Customer agrees not to (a) make more
copies than the number of Permitted Instances plus a
reasonable number of backups; (b) provide access to the
Software to anyone other than employees, contractors, or
consultants of Customer; (c) sublicense, transfer, assign,
distribute to any third party, pledge, lease, rent, or
commercially share the Software or any of Customer’s
rights under this Agreement; (d) use the Software for
purposes of providing a service bureau, including, without
limitation, providing third-party hosting, or third-party
application integration or application service provider-type
services, or any similar services; (e) use the Software in
connection with ultrahazardous activities, or any activity for
which failure of the Software might result in death or
serious bodily injury to Customer or a third party; or (f)
directly or indirectly, in whole or in part, modify, translate,
reverse engineer, decrypt, decompile, disassemble, make
error corrections to, create derivative works based on, or
otherwise attempt to discover the source code or
underlying ideas or algorithms of the Software.
Beta and Evaluation Licenses. Notwithstanding the
foregoing, if the Software is being provided for
demonstration, beta testing, or evaluation purposes, then
Customer agrees (a) to use the Software solely for such
purposes, (b) that the Software will not be used or
deployed in a production environment, and (c) that such
use shall automatically terminate upon the earlier of thirty
days from the date Customer receives the right to install
the Software, or Customer’s receipt of notice of
termination from TIBCO.
End User License Agreement
Additional Licenses. If Customer desires to increase the
number of Permitted Instances, Customer may request the
same by submission of an additional Ordering Document and
upon acceptance by TIBCO, Customer shall be permitted to
deploy such additional Permitted Instances, all of which shall
otherwise be subject to the terms of this Agreement.
Technical Support. Provided Customer has paid applicable
support fees (not included with Software fees unless
separately listed), TIBCO shall provide support for generally
available TIBCO Software on an annual basis commencing
on the Purchase Date, as follows (“Support”): Customer shall
designate as technical support contacts that number of
Customer’s employees as are permitted under the level of
Support purchased (contacts are changeable upon 48-hours
prior written notice to TIBCO). Each contact may contact
TIBCO for problem resolution during TIBCO’s published
support hours corresponding to the level of Support fees
paid.
Upon notice from a contact of a Software problem which can
be reproduced at a TIBCO support facility or via remote
access to Customer’s facility, TIBCO shall use reasonable
efforts to correct or circumvent the problem according to its
published support objectives. TIBCO reserves the right to
make changes only to the most currently available version.
TIBCO will use reasonable efforts to support the previously
released version of the Software for a maximum of six
months. Software may be transferred to another site or
operating system only upon written notice to TIBCO and
subject to TIBCO’s transfer policies and fees then in effect.
Software may be transferred without notice or additional cost
from one machine to another at the same site if the second
machine runs the same operating system software and
otherwise there is no increase in the Permitted Instances.
TIBCO shall have no obligation to support the Software (i) for
use on any computer system running other than the operating
system software for which the Software is approved (as set
forth in the Software documentation) and licensed hereunder,
or (ii) if Customer has modified the Software in breach of this
Agreement. TIBCO shall have no obligation to modify any
version of the Software to run with any new versions of any
operating system, or any other third party software or
hardware. If Customer purchases Support for any Software,
Customer must purchase the same level of Support for all
copies of the Software for which it is licensed.
Support may be extended for one year periods on the
anniversary of each Purchase Date at the standard amounts
set forth in its price list, for as long as TIBCO offers Support.
Customer may reinstate lapsed support for any then currently
supported Software by paying all Support fees in arrears and
any applicable reinstatement fee. Upgrades, patches,
enhancements, bug fixes, new versions and/or new releases
of the Software provided from time to time under Support
shall be used only as replacements to existing Permitted
Instances, and shall not be deemed to increase that number,
and use thereof shall be governed by the terms of this
Agreement, except for the first paragraph of the Limited
Warranty and any right of return or refund.
Consulting Services. Customer may request additional
services (“Services”) either in an Ordering Document, or by a
separate mutually executed work order, statement of work or
other work-request document incorporating this Agreement
(each, a “Work Order”). Unless otherwise expressly agreed to in a
Work Order, all Services and any work product therefrom shall be
(a) performed on a time and materials basis, plus meals, lodging,
travel, and other expenses reasonably incurred in connection
therewith, (b) deemed accepted upon delivery, and (c) exclusively
owned by TIBCO (except for confidential information of Customer
identified to TIBCO in the Ordering Document), including all right,
title and intellectual property or other right or interest therein.
Each Work Order is intended to constitute an independent and
distinct agreement of the parties, notwithstanding that each shall
be construed to incorporate all applicable provisions of this
Agreement. Fees for Services shall be due and payable in United
States dollars net30 from the date of TIBCO’s invoice.
Limited Warranty. If Customer obtained the Software directly
from TIBCO, then TIBCO warrants that for a period of thirty (30)
days from the Purchase Date: (i) the media on which the Software
is furnished will be free of defects in materials and workmanship
under normal use; and (ii) the Software will substantially conform
to its published specifications. This limited warranty extends only
to the original Customer hereunder. Customer’s sole and
exclusive remedy and the entire liability of TIBCO and its
suppliers under this limited warranty will be, at TIBCO’s option,
repair, replacement, or refund of the Software and applicable
Support fees, in which event this Agreement shall terminate upon
payment thereof.
This warranty does not apply to any Software which (a) is
licensed for beta, evaluation, testing or demonstration purposes
for which TIBCO does not receive a license fee, (b) has been
altered or modified, except by TIBCO, (c) has not been installed,
operated, repaired, or maintained in accordance with instructions
supplied by TIBCO, (d) has been subjected to abnormal physical
or electrical stress, misuse, negligence, or accident, or (e) is used
in violation of any other term of this Agreement. Customer agrees
to pay TIBCO for any Support or Services provided by TIBCO
related to a breach of the foregoing on a time, materials, travel,
lodging and other reasonable expenses basis. If Customer
obtained the Software from a TIBCO reseller or distributor, the
terms of any warranty shall be as provided by such reseller or
distributor, and TIBCO provides Customer no warranty with
respect to such Software.
EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE
SOFTWARE, SUPPORT AND SERVICES ARE PROVIDED “AS
IS”, ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS, AND WARRANTIES INCLUDING,
WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR
CONDITION OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, NONINFRINGEMENT,
SATISFACTORY QUALITY OR ARISING FROM A COURSE OF
DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY
EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE
LAW. NO WARRANTY IS MADE REGARDING THE RESULTS
OF ANY SOFTWARE, SUPPORT OR SERVICES OR THAT THE
SOFTWARE WILL OPERATE WITHOUT ERRORS, PROBLEMS
OR INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE
SOFTWARE WILL BE CORRECTED, OR THAT THE
SOFTWARE’S FUNCTIONALITY OR SERVICES WILL MEET
CUSTOMER’S REQUIREMENTS. NO TIBCO DEALER,
DISTRIBUTOR, AGENT OR EMPLOYEE IS AUTHORIZED TO
MAKE ANY MODIFICATIONS, EXTENSIONS OR ADDITIONS
TO THIS WARRANTY.
Limitation of Liability. IN NO EVENT WILL TIBCO BE LIABLE
FOR ANY LOST DATA, LOST REVENUE, LOST PROFITS,
DAMAGE TO REPUTATION, BUSINESS INTERRUPTION, OR
ANY OTHER INDIRECT, INCIDENTAL, CONSEQUENTIAL,
SPECIAL, PUNITIVE, EXEMPLARY OR ANY SIMILAR TYPE
DAMAGES ARISING OUT OF THIS AGREEMENT, THE USE OR
THE INABILITY TO USE THE SOFTWARE, OR THE
PROVISION OF ANY SUPPORT OR SERVICES, EVEN IF
TIBCO HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
IN NO EVENT SHALL TIBCO'S LIABILITY TO CUSTOMER,
WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE OR
PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS
BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE
PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING
DOCUMENT.
THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE
ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF
ITS ESSENTIAL PURPOSE. BECAUSE SOME STATES OR
JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION
OF CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE
ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER.
Confidentiality. Aspects of the Software, Support and Services,
including the specific design and structure thereof, constitute
trade secrets and/or copyrighted material of TIBCO and
Customer agrees not to disclose, provide, or otherwise make
available the same in any form to any third party. Customer
agrees to implement reasonable security measures to protect
trade secrets and copyrighted material and to affix to all copies of
Software or other confidential or trade secret information,
appropriate TIBCO copyright, confidentiality, and proprietary
notices.
Export. Software, including technical data, is subject to U.S.
export control laws, including the U.S. Export Administration Act
and its associated regulations, and may be subject to export or
import regulations in other countries. Customer agrees to comply
strictly with all such regulations and agrees to obtain all
necessary licenses to export, re-export, or import Software.
Government Use. If the Customer is an agency, department, or
other entity of the United States Government ("Government"), the
use, duplication, reproduction, release, modification, disclosure or
transfer of the Software, or any related documentation of any
kind, including technical data or manuals, is restricted in
accordance with Federal Acquisition Regulation ("FAR") 12.212
for civilian agencies and Defense Federal Acquisition Regulation
Supplement ("DFARS") 227.7202 for military agencies. The
Software is commercial computer software and commercial
computer software documentation. Use of the Software and
related documentation by the Government is further restricted in
accordance with the terms of this Agreement, and any
modification thereto.
Interoperability. To the extent required by law, at Customer’s
request, TIBCO shall provide Customer with the interface
information needed to achieve interoperability between the
Software and another independently created program, on
payment of TIBCO's applicable fee. Customer agrees to observe
strict obligations of confidentiality with respect to such
information.
Acceptance; Integration. An Ordering Document shall be
deemed accepted only by issuance of a TIBCO invoice and solely
for purposes of administrative convenience. None of the terms of
the Ordering Document (other than the Software product name,
number of Permitted Instances, level of Support, description of
Services, and fees due in connection therewith), shall apply for
any reason or purpose whatsoever, regardless of any statement
on any Ordering Document to the contrary, unless countersigned
by TIBCO. This Agreement constitutes the entire agreement
between the parties with respect to the use of the Software,
Support and Services, and supersedes all proposals, oral or
written, and all other representations, statements, negotiations
and undertakings relating to the subject matter hereof. All future
orders of Software, Support or Services by Customer from TIBCO
shall be deemed to occur under the terms of this Agreement (with
or without reference to this Agreement), unless expressly
superseded by a signed written Agreement between the parties.
Term and Termination. Customer may terminate this Agreement
at any time by destroying all copies of the Software. This
Agreement will terminate immediately without notice from TIBCO
if Customer fails to comply with any of its provisions if not cured
within fifteen days of such failure, or and, upon such termination,
Customer must cease using and return or destroy all copies of the
Software. Customer’s obligation to pay accrued charges and fees
as well as the sections entitled “Confidentiality”, “Limited
Warranty” and “Limitation of Liability” shall survive any such
termination.
Authority. You hereby represent and warrant that you have full
power and authority to accept the terms of this Agreement on
behalf of Customer, and that Customer agrees to be bound by
this Agreement.
General. Fees on the Ordering Document (all to be paid on the
latter of thirty days from Invoice by TIBCO or the date set forth in
the Ordering Document) do not include sales, use, withholding,
value-added or similar taxes, and Customer agrees to pay the
same, excluding therefrom taxes related to TIBCO’s income and
corporate franchise tax. Customer agree to pay all reasonable
costs incurred (including reasonable attorneys’ fees) in collecting
past due amounts under this Agreement. No delay in the
performance of any obligation by either party, excepting all
obligations to make payment, shall constitute a breach of this
Agreement to the extent caused by force majeure. Customer
hereby grants TIBCO and its independent auditors the right to
audit Customer’s compliance with this Agreement. If any portion
of this Agreement is found to be void or unenforceable, the
remaining provisions shall remain in full force and effect. This
Agreement shall be governed by and construed in accordance
with the laws of the State of California, United States of America,
as if performed wholly within the state and without giving effect to
the principles of conflict of law. The state and/or federal courts in
San Francisco, California, shall have exclusive jurisdiction of any
action arising out of or relating to this Agreement. The United
Nations Convention on Contracts for the International Sale of
Goods is excluded from application hereto. If any portion hereof is
found to be void or unenforceable, the remaining provisions of this
Agreement shall remain in full force and effect.
Definitions. In connection with this Agreement, the following
capitalized terms shall have the following meaning: “Agreement”
means this End User License Agreement; “Customer” means the
original purchaser or licensee of the Software and any permitted
successors and assigns; “Development” means used for software
development purposes only; “Enterprise” means an unlimited
number of Permitted Instances for a period of three years from
the Purchase Date (unless otherwise set forth in the Ordering
Document), at which time existing licenses convert to perpetual
and Customer may not thereafter deploy additional Permitted
Instances, and in any event, shall (during the three-year unlimited
deployment period) exclude any entity which acquires, is acquired
by, merged into, or otherwise combined with Customer if, upon
such combination, the combined annual revenues or head count
is greater by ten percent (10%) than exists as of the Purchase
Date (and Customer hereby agree to provide TIBCO with notice
of the number of Permitted Instances deployed at the end of such
three-year period within thirty days thereafter); “Fab” means
unlimited use for shop-floor manufacturing applications at a Site;
“Workstation” shall mean a single end-user computer that is
generally intended to be accessed by one person at a time;
“Ordering Document” means any purchase order or similar
document or agreement requesting Software, Support or
Services; “Permitted Instance(s)” means the number of copies of
Software running on a Server Instance, Workstation, User, or
Development basis, on a designated Platform, as set forth in an
Ordering Document, including, without limitation, Enterprise, Site
and Fab licensing; “Platform” means the operating system set
forth in an Ordering Document; “Purchase Date” means the date
of the Ordering Document; “Server Instance” means a computer
performing common services for multiple Desktop machines;
“Site” means an unlimited number of Permitted Instances at a
specific physical address set forth in the Ordering Document (or,
in the absence of any address, at Customer’s corporate
headquarters); “Software” means the software products listed in
an Ordering Document (except as provided in the second
paragraph hereof), in whole and in part, along with their
associated documentation; “TIBCO” means TIBCO Software Inc.;
and “User” means the number of named users with access to the
Software.
Copyright © 1994-2000 TIBCO Software Inc. ALL RIGHTS
RESERVED.
Addenda:
None
TIBCO Software Inc.
Apache Software Foundation
“This product includes software developed by the Apache
Software Foundation (http://www.apache.org/). Copyright
(c) 1999-2000 The Apache Software Foundation. All
rights reserved.
Any redistribution of this product (if otherwise permitted)
must contain the above copyright notice and the following
list of conditions in the documentation, software and/or
other materials provided with the distribution:
The name "Xerces" and "Apache Software Foundation"
must not be used to endorse or promote products derived
from this software without prior written permission. For
written permission, contact apache@apache.org.
Products derived from this software may not be called
"Apache," nor may "Apache" appear in their name, without
prior written permission of the Apache Software
Foundation.
THIS SOFTWARE PROVIDED BY THE APACHE
SOFTWARE FOUNDATION IS PROVIDED "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE APACHE SOFTWARE
FOUNDATION OR ITS CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.”
International Business Machines Corporation
This product includes software developed by International
Business Machines Corporation. Copyright (c)
International Business Machines. All rights reserved.
The terms of IBM Public License Version 1.0 apply to the
TIBCO End User License Agreement. Any provisions in
this License Agreement which differ from the terms of the
IBM Public License Version 1.0 are offered by TIBCO
Software Inc., alone, and not by any other party. In the
event provisions of this License Agreement differ from the
terms of the IBM Public License Version 1.0, you may
obtain the ICU source code by sending email to
support@tibco.com.
"IBM Public License Version 1.0
THE ACCOMPANYING PROGRAM IS PROVIDED
UNDER THE TERMS OF THIS IBM PUBLIC LICENSE
("AGREEMENT"). ANY USE, REPRODUCTION OR
Third Party License Agreements
DISTRIBUTION OF THE PROGRAM CONSTITUTES
RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
1. DEFINITIONS
"Contribution" means: a) in the case of International Business
Machines Corporation ("IBM"), the Original Program, and b)
in the case of each Contributor, i) changes to the Program,
and ii) additions to the Program; where such changes and/or
additions to the Program originate from and are distributed by
that particular Contributor. A Contribution 'originates' from a
Contributor if it was added to the Program by such
Contributor itself or anyone acting on such Contributor's
behalf. Contributions do not include additions to the Program
which: (i) are separate modules of software distributed in
conjunction with the Program under their own license
agreement, and (ii) are not derivative works of the Program.
"Contributor" means IBM and any other entity that distributes
the Program.
"Licensed Patents " mean patent claims licensable by a
Contributor which are necessarily infringed by the use or sale
of its Contribution alone or when combined with the Program.
"Original Program" means the original version of the software
accompanying this Agreement as released by IBM, including
source code, object code and documentation, if any.
"Program" means the Original Program and Contributions.
"Recipient" means anyone who receives the Program under
this Agreement, including all Contributors.
2. GRANT OF RIGHTS
a) Subject to the terms of this Agreement, each Contributor
hereby grants Recipient a non-exclusive, worldwide,
royalty-free copyright license to reproduce, prepare derivative
works of, publicly display, publicly perform, distribute and
sublicense the Contribution of such Contributor, if any, and
such derivative works, in source code and object code form.
b) Subject to the terms of this Agreement, each Contributor
hereby grants Recipient a non-exclusive, worldwide,
royalty-free patent license under Licensed Patents to make,
use, sell, offer to sell, import and otherwise transfer the
Contribution of such Contributor, if any, in source code and
object code form. This patent license shall apply to the
combination of the Contribution and the Program if, at the
time the Contribution is added by the Contributor, such
addition of the Contribution causes such combination to be
covered by the Licensed Patents. The patent license shall not
apply to any other combinations which include the
Contribution. No hardware per se is licensed hereunder.
c) Recipient understands that although each Contributor
grants the licenses to its Contributions set forth herein, no
assurances are provided by any Contributor that the Program
does not infringe the patent or other intellectual property
rights of any other entity. Each Contributor disclaims any
liability to Recipient for claims brought by any other entity
based on infringement of intellectual property rights or
otherwise. As a condition to exercising the rights and licenses
granted hereunder, each Recipient hereby assumes sole
responsibility to secure any other intellectual property rights
needed, if any. For example, if a third party patent license is
required to allow Recipient to distribute the Program, it is
Recipient's responsibility to acquire that license before
distributing the Program.
d) Each Contributor represents that to its knowledge it has
sufficient copyright rights in its Contribution, if any, to grant the
copyright license set forth in this Agreement.
3. REQUIREMENTS
A Contributor may choose to distribute the Program in object
code form under its own license agreement, provided that:
a) it complies with the terms and conditions of this Agreement;
and b) its license agreement: i) effectively disclaims on behalf of
all Contributors all warranties and conditions, express and
implied, including warranties or conditions of title and
non-infringement, and implied warranties or conditions of
merchantability and fitness for a particular purpose; ii) effectively
excludes on behalf of all Contributors all liability for damages,
including direct, indirect, special, incidental and consequential
damages, such as lost profits; iii) states that any provisions which
differ from this Agreement are offered by that Contributor alone
and not by any other party; and iv) states that source code for the
Program is available from such Contributor, and informs licensees
how to obtain it in a reasonable manner on or through a medium
customarily used for software exchange.
When the Program is made available in source code form: a) it
must be made available under this Agreement; and b) a copy of
this Agreement must be included with each copy of the Program.
Each Contributor must include the following in a conspicuous
location in the Program: Copyright © {date here}, International
Business Machines Corporation and others. All Rights Reserved.
In addition, each Contributor must identify itself as the originator
of its Contribution, if any, in a manner that reasonably allows
subsequent Recipients to identify the originator of the
Contribution.
4. COMMERCIAL DISTRIBUTION
Commercial distributors of software may accept certain
responsibilities with respect to end users, business partners and
the like. While this license is intended to facilitate the commercial
use of the Program, the Contributor who include the Program in a
commercial product offering should do so in a manner which does
not create potential liability for other Contributors. Therefore, if a
Contributor includes the Program in a commercial product
offering, such Contributor ("Commercial Contributor") hereby
agrees to defend and indemnify every other Contributor
("Indemnified Contributor") against any losses, damages and
costs (collectively "Losses") arising from claims, lawsuits and
other legal actions brought by a third party against the
Indemnified Contributor to the extent caused by the acts or
omissions of such Commercial Contributor in connection with its
distribution of the Program in a commercial product offering. The
obligations in this section do not apply to any claims or Losses
relating to any actual or alleged intellectual property infringement.
In order to qualify, an Indemnified Contributor must: a) promptly
notify the Commercial Contributor in writing of such claim, and b)
allow the Commercial Contributor to control, and cooperate with
the Commercial Contributor in, the defense and any related
settlement negotiations. The Indemnified Contributor may
participate in any such claim at its own expense. For example, a
Contributor might include the Program in a commercial product
offering, Product X. That Contributor is then a Commercial
Contributor. If that Commercial Contributor then makes
performance claims, or offers warranties related to Product X,
those performance claims and warranties are such Commercial
Contributor's responsibility alone. Under this section, the
Commercial Contributor would have to defend claims against the
other Contributors related to those performance claims and
warranties, and if a court requires any other Contributor to pay
any damages as a result, the Commercial Contributor must pay
those damages.
5. NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT,
THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT
LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE,
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR
A PARTICULAR PURPOSE. Each Recipient is solely responsible
for determining the appropriateness of using and distributing the
Program and assumes all risks associated with its exercise of
rights under this Agreement, including but not limited to the risks
and costs of program errors, compliance with applicable laws,
damage to or loss of data, programs or equipment, and
unavailability or interruption of operations.
6. DISCLAIMER OF LIABILITY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT,
NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL
HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING WITHOUT LIMITATION LOST
PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE
PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED
HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
7. GENERAL
If any provision of this Agreement is invalid or unenforceable
under applicable law, it shall not affect the validity or enforceability
of the remainder of the terms of this Agreement, and without
further action by the parties hereto, such provision shall be
reformed to the minimum extent necessary to make such
provision valid and enforceable.
If Recipient institutes patent litigation against a Contributor with
respect to a patent applicable to software (including a cross-claim
or counterclaim in a lawsuit), then any patent licenses granted by
that Contributor to such Recipient under this Agreement shall
terminate as of the date such litigation is filed. In addition, If
Recipient institutes patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Program
itself (excluding combinations of the Program with other software
or hardware) infringes such Recipient's patent(s), then such
Recipient's rights granted under Section 2(b) shall terminate as of
the date such litigation is filed.
All Recipient's rights under this Agreement shall terminate if it
fails to comply with any of the material terms or conditions of this
Agreement and does not cure such failure in a reasonable period
of time after becoming aware of such noncompliance. If all
Recipient's rights under this Agreement terminate, Recipient
agrees to cease use and distribution of the Program as soon as
reasonably practicable. However, Recipient's obligations under
this Agreement and any licenses granted by Recipient relating to
the Program shall continue and survive.

IBM may publish new versions (including revisions) of this

Agreement from time to time. Each new version of the Agreement
will be given a distinguishing version number.

The Program (including Contributions) may always be distributed

subject to the version of the Agreement under which it was
received.

In addition, after a new version of the Agreement is published,

Contributor may elect to distribute the Program (including its
Contributions) under the new version. No one other than IBM has
the right to modify this Agreement. Except as expressly stated in
Sections 2(a) and 2(b) above, Recipient receives no rights or
licenses to the intellectual property of any Contributor under this
Agreement, whether expressly, by implication, estoppel or
otherwise. All rights in the Program not expressly granted under
this Agreement are reserved.

This Agreement is governed by the laws of the State of New York

and the intellectual property laws of the United States of America.
No party to this Agreement will bring a legal action under this
Agreement more than one year after the cause of action arose.
Each party waives its rights to a jury trial in any resulting
litigation."

Microstar Software.

Portions of this Software may include software provided by

Microstar Software. Copyright (c) 1997, 1998 by Microstar
Software. All rights reserved.
Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Conventions Used in this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Related Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxviii
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix

Chapter 1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Request/Reply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Building Service Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Load Balancing and Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
How URLs Are Constructed by an HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Request to a Service in an RVDQ Service Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Request to a Service in TAW Service Registry Pool. . . . . . . . . . . . . . . . . . . . . . . . . . 7
Setting Service Instance Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Before Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Supported Web Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Optional Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
TIB/Rendezvous API Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Installing on Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
To Install on Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Installing on Unix Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Uninstalling on Unix Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 3 Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Configuring IIS with JRun 2.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

TIB/Adapter for Web User’s Guide Page xi

Contents

Configure the TAW Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Configuring IIS with JRun 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Configure the TAW Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Configuring iPlanet Web Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Verifying Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Configuring Service Instance and Servlet Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 38
GUI Client (Web Browser) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Non GUI Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configuring TIB/Rendezvous Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Mapping Arbitrary URLs to the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4 Using TIB/Hawk Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Starting TIB/Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Starting TIB/Hawk Software on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Starting TIB/Hawk Software on Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
The Auto-Discovery Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Available Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
TAW5agent:<agent_id> Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
COM.TIBCO.ADAPTER.TAW:<agent_id> Methods . . . . . . . . . . . . . . . . . . . . . . . . . 53
getConfig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
getConfigProperties() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
getDebugLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
getDebugSubject(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
getServletContext() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
getVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
_onUnsolictedMsg(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
setDebugLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
setDebugSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 5 C++ API for TIB/Rendezvous 6.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
The Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Page xii TIB/Adapter for Web User’s Guide

 Contents

Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
C++ Example Service Instances for TIB/Rendezvous 6.x . . . . . . . . . . . . . . . . . . . . 67
TAWrvService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
TAWrvService::TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
TAWrvService::~TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
TAWrvService::disableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
TAWrvService::enableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
TAWrvService::fence() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
TAWrvService::get...() Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
getDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
getDispatchQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
getErrorMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
getRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
getTibrvCmQueueTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
getTibrvTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
TAWrvService::isEnabled() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
TAWrvService::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
TAWrvService::onDirectMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
TAWrvService::onMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
TAWrvService::setDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
TAWrvService::setRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
TAWrvRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
TAWrvRequest::TAWrvRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TAWrvRequest::get...() Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
getHttpHeader(name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
getHttpHeaders() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
getHttpMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getHttpUri() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getHttpVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getProtocolVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getUrlParameter(name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getUrlParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getUrlPath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getUrlResource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
getHttpReplyHeader(name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
getHttpReplyHeaders() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
getHttpReplyOpaqueEntityBody(rLen) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

TIB/Adapter for Web User’s Guide Page xiii

Contents

getHttpReplyReasonPhrase() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
getHttpReplyStatusCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
getHttpReplyStringEntityBody(rLen) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
getReplyMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
getReplyProtocolVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
TAWrvRequest::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
TAWrvRequest::reply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
TAWrvRequest::set...() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
setHttpReplyHeader(name value) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
setHttpReplyOpaqueEntityBody(body, bodyLen) . . . . . . . . . . . . . . . . . . . . . 90
setHttpReplyReasonPhrase(phrase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
setHttpReplyStatus(code, phrase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
setHttpReplyStatusCode(code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
setHttpReplyStringEntityBody(body) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
APSvc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
APSvc::APSvc(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
APSvc::appendToHeartbeat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
APSvc::disable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
APSvc::enable(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
APSvc::init(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
APSvc::onMsg(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
APSvc::onTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
APSvc::sendHeartbeat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
APSvc::start() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
APSvc::startHeartbeating() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
APSvc::terminate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Compiling the Service Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Simple Service C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
simplesvc.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
File Service C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
filesvc.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
WorldHello Service C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Page xiv TIB/Adapter for Web User’s Guide

 Contents

Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

worldhello.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
HelloGoodbye Service C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
hellogoodbye.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
MultiDispatcher Service C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
multiDispatcher.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Simple Service Registry C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
simplesvcReg.cc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Chapter 6 Java API Reference for TIB/Rendezvous 6.x. . . . . . . . . . . . . . . . . . . . . 129

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Java Example Service Instances for TIB/Rendezvous 6.x . . . . . . . . . . . . . . . . . . . 131
com.tibco.portal.gw.web.api.rv6.TAWrvService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
TAWrvService(transport) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
TAWrvService(transport, queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
TAWrvService(transport, queue, requestSubject) . . . . . . . . . . . . . . . . . . . 135
TAWrvService(transport, queue, requestSubject, directRequestSubject) . 136
TAWrvService(cmqQueueTransport) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
TAWrvService(cmqQueueTransport, queue) . . . . . . . . . . . . . . . . . . . . . . . 136
TAWrvService(cmqQueueTransport, queue, requestSubject) . . . . . . . . . . 137
TAWrvService(cmqQueueTransport, queue, requestSubject, directRequest-
Subject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
TAWrvService.get...() Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
getDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
getDispatchQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
getRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
getTibrvCmQueueTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
getTibrvTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

TIB/Adapter for Web User’s Guide Page xv

Contents

TAWrvService.onMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
TAWrvService.onDirectMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
TAWrvService.setRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
TAWrvService.setDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
TAWrvService.enableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
TAWrvService.disableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
TAWrvService.isEnabled() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
com.tibco.portal.gw.web.api.rv6.TAWrvRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
TAWrvRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TAWrvRequest.get...() Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
getHttpHeader(name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
getHttpHeaders() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getHttpMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getHttpUri() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getHttpVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getProtocolVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getUrlParameter(name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getUrlParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getUrlPath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
getUrlResource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getHttpReplyEntityBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getHttpReplyHeader(name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getHttpReplyHeaders() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getHttpReplyReasonPhrase() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getHttpReplyStatusCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getReplyMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getReplyProtocolVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
TAWrvRequest.reply...() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
reply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
reply(entityBody) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
reply(entityBody, statusCode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
reply(entityBody, statusCode, reasonPhrase) . . . . . . . . . . . . . . . . . . . . . . . 154
reply(entityBody) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
reply(entityBody, statusCode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
reply( entityBody, statusCode, reasonPhrase) . . . . . . . . . . . . . . . . . . . . . . 154
TAWrvRequest.set...() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
setHttpReplyEntityBody(body) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
setHttpReplyHeader(name value) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
setHttpReplyReasonPhrase( phrase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
setHttpReplyStatus(code, phrase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Page xvi TIB/Adapter for Web User’s Guide

 Contents

setHttpReplyStatusCode(code) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
com.tibco.portal.gw.web.api.rv6.TAWrvException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
com.tibco.portal.svcreg.APSvc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
APSvc.appendToHeartbeat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
APSvc.disable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
APSvc.enable(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
APSvc.init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
APSvc.run() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
APSvc.terminate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
com.tibco.portal.svcreg.APSvcImpl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
APSvcImpl.APSvcImpl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
APSvcImpl.appendToHeartbeat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
APSvcImpl.disable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
APSvcImpl.enable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
APSvcImpl.init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
APSvcImpl.onMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
APSvcImpl.onTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
APSvcImpl.run() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
APSvcImpl.sendHeartbeat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
APSvcImpl.startHeartbeating(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
APSvcImpl.terminate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Compiling the Service Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Simple Service Java Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
SimpleSvc.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
File Service Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
FileSvc.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
WorldHello Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
WorldHello.java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
HelloGoodbye Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

TIB/Adapter for Web User’s Guide Page xvii

Contents

Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

HelloGoodbye.java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
MultiDispatcher Service Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Simple Service Registry Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Raw Service Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Appendix A C++ API Reference for TIB/Rendezvous 5.x . . . . . . . . . . . . . . . . . . . 201

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
The Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Service Pools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
TAWrvService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
TAWrvService::TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
TAWrvService::~TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
TAWrvService::onRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
TAWrvService::onDirectRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
TAWrvService::setRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
TAWrvService::setDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
TAWrvService::getDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
TAWrvService::getRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
TAWrvService::enableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
TAWrvService::disableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
TAWrvService::isEnabled() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
TAWrvService::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
TAWrvService::getRvSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
TAWrvService::getErrorMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
TAWrvRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
TAWrvRequest::getReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
TAWrvRequest::getUrlPath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
TAWrvRequest::getUrlResource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Page xviii TIB/Adapter for Web User’s Guide

 Contents

TAWrvRequest::getHttpMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
TAWrvRequest::getHttpUri() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
TAWrvRequest::getHttpVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
TAWrvRequest::getHttpRequestEntityBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
TAWrvRequest::getUrlParameter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
TAWrvRequest::getHttpRequestHeader() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
TAWrvRequest::setHttpReplyEntityBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
TAWrvRequest::setHttpReplyHeader() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
bTAWrvRequest::setHttpStatusCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
TAWrvRequest::getRvdqSenderName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
TAWrvRequest::getRvdqSequenceNumber() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
TAWrvRequest::reply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
TAWrvRequest::getProtocolVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
TAWrvRequest::setHttpReasonPhrase() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
TAWrvRequest::isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
TAWrvRequest::getUrlParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
TAWrvRequest::getHttpRequestHeaders() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
C++ Example Service Instances for TIB/Rendevous 5.x . . . . . . . . . . . . . . . . . . . . . . . 243
Compiling the Service Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
simplesvc.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
filesvc.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
worldhello.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
hellogoodbye.cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Appendix B Java API Reference for TIB/Rendezvous 5.x . . . . . . . . . . . . . . . . . . 259

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
com.tibco.portal.gw.web.api.rv5.TAWrvService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
TAWrvService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
TAWrvService.onRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
TAWrvService.onDirectRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
TAWrvService.setRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
TAWrvService.setDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
TAWrvService.getDirectRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
TAWrvService.getRequestSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
TAWrvService.enableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

TIB/Adapter for Web User’s Guide Page xix

Contents

TAWrvService.disableRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
TAWrvService.isEnabled() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
TAWrvService.getRvSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
TAWrvService.getRvCmqSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
com.tibco.portal.gw.web.api.rv5.TAWrvRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
TAWrvRequest.getReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
TAWrvRequest.getUrlPath() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
TAWrvRequest.getUrlResource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
TAWrvRequest.getHttpMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
TAWrvRequest.getHttpUri() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
TAWrvRequest.getHttpVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
TAWrvRequest.getHttpRequestEntityBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
TAWrvRequest.getUrlParameter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
TAWrvRequest.getUrlParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
TAWrvRequest.getHttpRequestHeader() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
TAWrvRequest.getHttpRequestHeaders() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
TAWrvRequest.setHttpReplyEntityBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
TAWrvRequest.setHttpReplyHeader() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
TAWrvRequest.setHttpStatusCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
TAWrvRequest.getRvdqSenderName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
TAWrvRequest.getRvdqSequenceNumber() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
TAWrvRequest.reply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
TAWrvRequest.getProtocolVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
TAWrvRequest.setHttpReasonPhrase() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Java Example Service Instances for TIB/Rendezvous 5.x. . . . . . . . . . . . . . . . . . . . . . . 298
Compiling the Service Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
SimpleSvc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
FileSvc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
WorldHello . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
HelloGoodbye . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Appendix C TIB/Rendezvous 6.x Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Request and Reply TibrvMsg Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
RVDQ Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Setting up RVDQ Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Page xx TIB/Adapter for Web User’s Guide

 Contents

Creating Sessions within RVDQ Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Appendix D TIB/Rendezvous 5.x Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Request and Reply RvMsg Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
RVDQ Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Setting up RVDQ Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Creating Sessions within RVDQ Service Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

TIB/Adapter for Web User’s Guide Page xxi

Contents

Page xxii TIB/Adapter for Web User’s Guide

Preface

This manual describes how to install, configure, and administer the TIB/Adapter for Web
servlet. It also describes how to build TIB/Adapter for Web service applications using the
C++ API, the Java API, or the TIB/Rendezvous Facilities protocol.

Topics

Conventions Used in this Manual, page xxiv

Glossary, page xxvi

Related Documents, page xxviii

How to Contact TIBCO Customer Support, page xxix

TIB/Adapter for Web User’s Guide Page xxiii

Conventions Used in this Manual

Conventions Used in this Manual

This manual uses the following typeface conventions:

Convention Used to

Code examples, List program output, listings of code examples, file names,
file names, etc.
commands, configuration file parameters, and literal
programming elements in running text.

Command line Indicate characters in a command line that you must type
characters you exactly as shown. Also used to emphasize particular strings
type in code examples.

<Replace this text with an Indicate text that should be replaced with an actual value.
actual value> This applies to command line syntax, code samples, and
configuration file parameters.

Graphical User In a graphical user interface (such as Microsoft

Interface Inputs Windows-based or UNIX X Window applications), used to
indicate actions, for example, items you click or type.
Submenus and options of a menu item are indicated with an
angle bracket, for example, Menu>Submenu.

Italic Refer to document title names in statements that refer you to

other documents; emphasis in regular running text.

Page xxiv TIB/Adapter for Web User’s Guide

 Preface

The notational conventions in the table below are used for describing command syntax.
When used in this context, do not type the brackets listed in the table as part of a
command line.

Notation Description Used to

[ ] Brackets Enclose an optional item in the command syntax.

<> Angle Enclose a name (usually in Italic) that represents an

Brackets argument for which you substitute a value when you
use the command.

{} Curly Enclose two or more items among which you can

Brackets choose only one at a time. Vertical bars (|) separate the
choices within the curly brackets.

... Ellipsis Indicate that you can repeat an item any number of
times in the command line.

TIB/Adapter for Web User’s Guide Page xxv

Glossary

Glossary

Acronym Meaning

CGI Common Gateway Interface. A way of interfacing computer programs

with HTTP or WWW servers, so that a server can offer interactive sites
instead of just static text and images.

HTTP Hypertext Transfer Protocol.

HTTP Client An application, such as a web browser, that makes requests to an

HTTP Server over an Intranet or the Internet. Typically the HTTP
client is a web browser but it can be any application that can send and
receive using HTTP.

HTTP Server An application, typically a web server, that provides data in response
to HTTP client requests transmitted over an Intranet or the Internet.

IIS Internet Information Server

Service A TIB/Rendezvous based application containing business logic that

Application uses a TIB/Adapter for Web Servlet to provide information to HTTP
clients, such as web browsers.

Service Pool A fault-tolerant and load-balanced group of service applications that

use TIB/Rendezvous distributed queues to guarantee 1 of N request
delivery.

Servlet An applet that runs on the server side. See

java.sun.com/products/servlet/ for details.

URI Uniform Resource Identifier, a generic way of uniquely identifying a

network resource. See RFC2616 (Hypertext Transfer Protocol --
HTTP/1.1).

Page xxvi TIB/Adapter for Web User’s Guide

 Preface

Acronym Meaning

URL Uniform Resource Locator, a type of URI that identifies the network
resource by location. URI and URL are often used interchangeably in
the context of HTTP as URLs are the only type of URI that are in
common use.
See RFC1738 (Uniform Resource Locators (URL)).

Web Server See HTTP Server.

TIB/Adapter for Web User’s Guide Page xxvii

Related Documents

Related Documents

Documentation available from TIBCO Software Inc.:

— The TIB/Rendezvous™ documentation set.
— The TIB/Hawk™ documentation set.
— The TIB/Adapter™ SDK documentation set.

Page xxviii TIB/Adapter for Web User’s Guide

 Preface

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact
TIBCO customer support by e-mail or mail using the following:
E-mail: support@tibco.com
URL: www.tibco.com
Address:
Customer Support
TIBCO Software Inc.
3165 Porter Drive
Palo Alto, CA 94304-1213

TIB/Adapter for Web User’s Guide Page xxix

How to Contact TIBCO Customer Support

Page xxx TIB/Adapter for Web User’s Guide

Chapter 1 Overview

TIB/Adapter for Web (TAW) is a bridge that allows HTTP clients to issue requests
through a servlet to TIB/Rendezvous-based service instances. It allows you to build
distributed, fault-tolerant, and load-balanced service instances that can be accessed by
HTTP clients, such as web browsers or peer B2B applications.
This product is particularly useful as a way to extend the reach of existing
TIB/Rendezvous based enterprise systems to the Internet, or as a higher performance,
more scalable alternative to the Common Gateway Interface (CGI), or as a foundation for
HTTP-based B2B systems.

Topics

Components, page 2

Request/Reply, page 3

Building Service Instances, page 4

How URLs Are Constructed by an HTTP Client, page 7

TIB/Adapter for Web User’s Guide Page 1

Components

Components

TIB/Adapter for Web provides these components:

A servlet that is loaded with a web server which maps HTTP requests to
TIB/Rendezvous requests.

A TIB/Rendezvous-based protocol to exchange information between the servlet and
service instance.

Two service application programmer interfaces (APIs) that understand this protocol:
— C++ API
— Java API
You must provide these components:

If using Microsoft Internet Information Server, JRun from Allaire (www.allaire.com)
must be available on your system.

TIB/Rendezvous based service instances that process messages from HTTP clients.
The flow of information among these components is shown next.

Figure 1 TIB/Adapter for Web architecture

Web server
Web browser or
HTTP
other HTTP client TIB/Adapter for
Web servlet
RvMsg

TIB/Rendezvous
RvMsg
RvMsg

Service Service
Service
Service
application application
application
application

Unique service
TIB/Rendezvous
Distributed Queue
service pool

Page 2 TIB/Adapter for Web User’s Guide

 Chapter 1 Overview

Request/Reply

The TAW servlet enables a web server to recognize HTTP requests addressed to a
TIB/Rendezvous-based service instance. The servlet translates between HTTP and
TIB/Rendezvous and manages the request during its lifetime. Request/reply semantics
are used as follows:

Standard web browsers, or custom HTTP clients issue HTTP requests to a web server
that has loaded the servlet. The URL identifies the target of the request, either by a
TIB/Rendezvous subject name or service name, depending on the load-balancing
approach taken.

The servlet maps the URL into a TIB/Rendezvous subject name, translates the HTTP
request, including headers, into an TIB/Rendezvous message and publishes the
request.

A service instance that is listening to that subject processes the request and replies to
the servlet using return address information present in the request.

The servlet parses the reply TIB/Rendezvous message and transmits its contents to
the client.
See the TIB/Rendezvous Concepts manual for details about subject names.

TIB/Adapter for Web User’s Guide Page 3

Building Service Instances

Building Service Instances

You can use the TAW APIs to build service instances or you can implement the simple,
request/reply TAW protocol. The TAW APIs make it easy for you to create pools of
service instances that are scalable and fault tolerant. You can use either TIB/Rendezvous
Distributed Queues (RVDQ), or the TAW service registry (APSvc API) to make your
service instances available for this purpose.
On supported platforms the TAW APIs are the best choice for most programmers. Each
API provides a convenient layer to simplify interaction with TIB/Rendezvous version 5.x
and version 6.x.
Service instances need not use these APIs if they conform to the simple, public service
TAW protocol specification. This is helpful in the event that your service instance must be
written using a language or compiler that TAW does not support when TIB/Rendezvous
does support it. A description of the TAW message protocol requirements is provided in
the appendices of this book.
The details of the TIB/Rendezvous API and protocols are described in the
TIB/Rendezvous documentation set.

Load Balancing and Fault Tolerance

TIB/Adapter for the Web gives system designers two mechanisms to support load
balancing and fault tolerance: RVDQ and the TAW service registry.
RVDQ service pool. When the RVDQ API is used, the TAW servlet sends the request
TibrvMsg to the subject specified by the URL in the HTTP request. It does not know if any
programs are listening on that subject or not. As shown next, if an RVDQ-based pool of
service instances are listening to that subject, the RVDQ dispatcher guarantees that only
one of member of the pool processes the request and returns a reply.
The TAW servlet is not involved in any decision-making with respect to which member of
the pool should process the request. The advantage of this approach is that it is very easy
to code. However, when request volume becomes very high, the RVDQ dispatcher can
become a bottleneck.

Page 4 TIB/Adapter for Web User’s Guide

 Chapter 1 Overview

Figure 2 RVDQ Service Pool

Web server
HTTP
TAW SERVLET

Service application
(RVDQ Dispatcher) Service
application
Service
application
Service
application
Service
application
Service
application

TIB/Rendezvous Distributed Queue Service Pool

TAW service registry. If service instances use the APSvc API (in addition to the TAW
API), the TAW servlet maintains state information in an internal registry about all the
service instances that it can reach. These service instances register themselves during
initialization, through the APSvc API. This registration consists of declaring themselves to
be an instance of some generic "service" that is listening for subjects on a globally unique
subject name (nominally an inbox). Following this registration, the service instance sends
out heartbeats that allows TAW to determine when the service has become available.
As shown next, when a request occurs, TAW determines which instance to contact based
upon the scheduling discipline selected (that is set in TIB/Repository), and
heartbeat-based usage and availability information. The advantage of this approach is
better scalability, as the bottleneck no longer is the service instance, but is instead, the web
server. This bottleneck can be resolved using traditional upstream solutions such as Cisco
Director.

TIB/Adapter for Web User’s Guide Page 5

Building Service Instances

Figure 3 TAW Service Registry

Web server

TAW servlet
HTTP
Registry

A B C D E

Service
Service
application A
application E

Service
Service Service
application B
application C application D

TAW Service Registry Pool

Page 6 TIB/Adapter for Web User’s Guide

 Chapter 1 Overview

How URLs Are Constructed by an HTTP Client

An HTTP client issues requests to service instances by contacting the web server that
contains the TAW servlet.

Request to a Service in an RVDQ Service Pool

An HTTP client uses the following syntax to construct and send a request via the web
server and servlet to a service instance that is in an RVDQ service pool:
http://<web_server_name>/servlet/TAW?subject=<subject_name>

The web_server_name is that of the web server that has loaded the TAW servlet. The
web server name is nominally given as <machine_name>[:port].

The subject_name is the TIB/Rendezvous subject name on which the service instance
listens for requests to process.
For example, the following URL specifies a request to either a single service instance or a
pool of RVDQ based service instances. The web server and servlet is running on the
machine boomer. The subject name is xyz.
http://boomer/servlet/TAW?subject=xyz

Request to a Service in TAW Service Registry Pool

An HTTP client uses the following syntax to construct and send a request via the web
server and servlet to a service instance that is in a TAW service registry pool:
http://<web_server_name>/servlet/TAW?service=<service_name>

The web_server_name is that of the web server that has loaded the TAW servlet. The
web server name is nominally given as <machine_name>[:port].

The service_name is the service instance to contact to process the request.
For example, the following URL specifies a request to a service instance. The web server
and servlet is running on the machine boomer. The service name is myservice.
http://boomer/servlet/TAW?service=myservice

TIB/Adapter for Web User’s Guide Page 7

How URLs Are Constructed by an HTTP Client

Setting Service Instance Defaults

You can change the defaults for service parameters such as the service to servlet
connection timeout, and the HTML file displayed when a timeout occurs, the service is
not up, or an internal error occurs. You can also change the announce and heartbeat
subject name and the server allocation method. See Configuring Service Instance and
Servlet Parameters on page 38 for more information.

Page 8 TIB/Adapter for Web User’s Guide

Chapter 2 Installation

This chapter provides instructions on installing the TIB/Adapter for Web software and
verifying the success of the installation.

Topics

Before Installing, page 10

Installing on Windows NT, page 12

Installing on Unix Systems, page 13

TIB/Adapter for Web User’s Guide Page 9

Before Installing

Before Installing

This section lists supported operating systems, web servers and required software. It also
lists optional software.

Supported Operating Systems

Windows NT 4.0 Server with Service Pack 5.

Solaris 2.6 or better with the latest recommended patches.

Supported Web Servers

TIB/Adapter for Web has been tested and is supported on the following web servers:

Microsoft Internet Information Server (IIS) 4.0 running on Windows NT and extended
with Jrun (release 2.3 or 3.0) from Allaire.

iPlanet Web Server Enterprise Edition 4.1 running on Solaris.

Required Software
The following products are required and are available separately from TIBCO Software
Inc.:

TIB/Rendezvous software, version 6.3 or better.
TIB/Rendezvous can be installed before or after installing TIB/Adapter for Web
software. Ensure you have sufficient TIB/Rendezvous daemon and TIB/Rendezvous
Router daemon licenses. Since TIB/Adapter for Web uses TIB/Rendezvous as the
underlying communication layer, you need to request enough licenses for all
networks (e.g., client subnets, server subnets, development subnets, etc.). If you do not
have enough TIB/Rendezvous licenses, please contact your TIBCO Software Inc.
representative.

TIB/Repository 3.2.2 or better.

TIB/Adapter SDK 3.2.0 or better.

TIB/AdapterAdminstrator 3.2.0 or better.

Page 10 TIB/Adapter for Web User’s Guide

 Chapter 2 Installation

The following product is required if you are using Microsoft Internet Information Server.
The product is available from Allaire (Go to www.Allaire.com for more information.)

JRun 2.3.3 or JRun 3.0 (allows Java servlets to run under IIS web servers).
The following product is required and is typically installed by the TIB/Repository
installation procedure:

Java Runtime Environment (JRE) 1.2.2.

Optional Software

TIB/Hawk software, version 3.0 or better, available separately from TIBCO Software
Inc.

TIB/Rendezvous API Support

Under Windows NT Only

The TIB/Rendezvous 6.x and 5.x Java APIs are supported.

Only the TIB/Rendezvous 6.x C++ API is supported (with the Visual Basic C++
compiler). The TIB/Rendezvous 5.x C++ API is not supported.

Under Solaris Only

The TIB/Rendezvous 6.x and 5.x Java APIs are supported.

Both the TIB/Rendezvous 6.x and 5.x C++ APIs are supported. To use the
TIB/Rendezvous 6.x C++ API, you need the corresponding Sparcworks 5.0 compiler.
To use the TIB/Rendezvous 5.x C++ API, you need the corresponding Sparcworks 4.2
compiler.

TIB/Adapter for Web User’s Guide Page 11

Installing on Windows NT

Installing on Windows NT

The software should be installed on a PC with a Pentium II 233 MHz or better.

To Install on Windows NT
You install the software using InstallShield. You need administrator privileges for your
system. Follow these steps to install the software:
1. Insert the installation CDROM or download the software and double-click the
installation icon.
The installation software starts unpacking the software and prompts for an
installation folder location.
2. InstallShield then checks whether the appropriate version of TIB/Rendezvous is
installed. If it is not currently installed on your system, you are advised to install it at a
later time.
3. InstallShield launches and checks for the correct JRE version. If the JRE is not found
under the TIB_JAVA_HOME environment variable, it is created and the JRE is
automatically installed by the installation program.
4. After installation is complete, you are asked whether you would like to view the
README file. Select or deselect the check box, then click Finish.
5. Go to Chapter 3, Administration, on page 15 to configure your web server to use the
servlet.

Page 12 TIB/Adapter for Web User’s Guide

 Chapter 2 Installation

Installing on Unix Systems

You can get the software from an FTP site as directed by your TIBCO Sales Representative
or CDROM.

If the software is downloaded from an FTP site, you must unpack the software before
installing it.

If installing the software from a CDROM, change directory to your platform directory
and proceed to step 6.
1. Change directory to the temporary directory to hold the installation file that will be
downloaded from the FTP site. For example:
cd /tmp

2. Go to the FTP site and download the software to the temporary directory.
3. Uncompress the installation file.
uncompress <installation_file>.tar.Z
4. Create another temporary directory and change directory to it:
mkdir /tmp/tawinstalltmp
cd /tmp/tawinstalltmp

5. Uncompress the installation file and execute the tar command against it. (The
installation file must not be in the directory where the files will be unpacked.) For
example:
tar xvf /tmp/<installation_file>.tar

6. Execute the tibinstall script:

./tibinstall

Two installation types may be available, native and tar. If both are available, when the
installation procedure starts, you will be prompted to choose a type.
— Choose native if you have root access and want the software to be recorded in the
system software package database. If you choose native, the installation location
defaults to /opt/tibco/adweb/.
— Choose tar if you do not want to install the software as root. The software will not
be recorded in the system software package database. You will be prompted for an
absolute directory path name where the software is to be installed.
7. Move the HTML files and default directory and its contents found in the
<install_dir>/data directory to your web server’s Primary Document Directory.

TIB/Adapter for Web User’s Guide Page 13

Installing on Unix Systems

8. Go to Chapter 3, Administration, on page 15 to configure your web server to use the

servlet.

Uninstalling on Unix Systems

To remove a TIB/Adapter for Web software native installation, obtain superuser (that is,
root) access to the machine on which the software is installed and enter the following
command:

Platform Command

Sun (native installation) /usr/sbin/pkgrm TIBadweb

To remove a TIB/Adapter for Web software tar installation, change to your installation
directory and use the delete command for your Unix operating system.

Page 14 TIB/Adapter for Web User’s Guide

Chapter 3 Administration

This chapter provides configuration and administration information.

Topics

Before Starting, page 16

Configuring IIS with JRun 2.3, page 17

Configuring IIS with JRun 3.0, page 22

Configuring iPlanet Web Server, page 30

Verifying Installation and Configuration, page 36

Configuring Service Instance and Servlet Parameters, page 38

Configuring TIB/Rendezvous Parameters, page 42

Mapping Arbitrary URLs to the Servlet, page 43

TIB/Adapter for Web User’s Guide Page 15

Before Starting

Before Starting

Before starting, make sure that your web server is installed correctly by starting the web
publishing service. If your web server is installed in the default location, type the
following in your web browser:
http://<host_name>/

otherwise, type:
http://<host_name>:<port number>/

Your web server’s default home page should display in your web browser.

Page 16 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

Configuring IIS with JRun 2.3

You must ensure that JRun is operational and configured correctly using the installation
verification tools supplied by Allaire. Type the following in your Address field in Internet
Explorer to test the JRun installation:
http://<web_server_name>/servlet/Counter

If the URL displays correctly proceed with the instructions found in this section. If the
URL does not display correctly consult your JRun documentation for instructions on how
to proceed.

Configure the TAW Servlet

Before sending a request to the servlet, you must configure JRun with the location of the
TAW .jar files and .dat (repository) file. Both tasks are done in the JRun Service
Manager.

1. Invoke the JRun Service Manager and click Start.

TIB/Adapter for Web User’s Guide Page 17

Configuring IIS with JRun 2.3

2. In the JRun Administration tool, click General, then click Java.

3. In the Java Classpath (java.exe only) field, type the location of the .jar files
(separated by a semicolon) as shown next (for Windows NT). Note that drive c is used
in the example. You should use the drive name on which the software is installed, if it
is different.
— c:/tibco/Repository/jars/TIBRepoClient32.jar;
— c:/tibco/Adapter/SDK/java/Maverick32.jar;
— c:/tibco/tibrv/lib/tibrvj.jar;
— c:/tibco/adweb/java/taweb.jar;

Page 18 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

4. Click Save, then click Services. A dialog box similar to the following displays. Under
Service ID, click the jse service and click Service Config.

5. In the jse (Service Config) dialog box, click Aliases. Click Add to add a new alias
setting. The dialog box should be similar to the following screen.

6. Information must be added in the Name, Class Name and Init Arguments fields:
a. In Name, type TAW
b. In Class Name, type com.tibco.portal.gw.web.TAW
c. Double-click in the Init Arguments field. The following dialog box appears. Click
Add to add a line for the entry. In Name, type configFile. In Value, type the
location of the TIB/Repository file. Set the TAW debug subject and debug level

TIB/Adapter for Web User’s Guide Page 19

Configuring IIS with JRun 2.3

(note that there is no space after the comma). For example:

configFile=c:/tibco/adweb/data/taw5config.dat.,
debugSubject=taw.debug.jrun,debugLevel=0. Click OK to apply your changes
and close the dialog box.

7. Click the Pre-Load box so a check mark displays. The dialog box should look similar
to the following:

Page 20 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

8. Click Save, then click Close. In the next dialog box, click Close to end your session
with the JRun Service Manager.
9. Reboot your system.
10. Go to Verifying Installation and Configuration on page 36 to ensure the configuration
and installation is correct.

TIB/Adapter for Web User’s Guide Page 21

Configuring IIS with JRun 3.0

Configuring IIS with JRun 3.0

You must ensure that JRun is operational and configured correctly using the installation
verification tools supplied by Allaire. Type the following in your Address field in Internet
Explorer to test the JRun installation:
http://<web_server_name>/demo

If the URL displays correctly, click the example servlets and test. If the URL does not
display correctly consult your JRun documentation for instructions on how to proceed.
Before sending a request to the TAW servlet, you must configure JRun with the location of
the TAW .jar files and .dat (repository) file. Both tasks are done in the JRun Service
Manager.

Page 22 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

Configure the TAW Servlet

1. Display the JRun admin tool in your web browser.
2. In the left frame, expand JRun Default Server.

3. Under JRun Default Server, double click Java Settings.

4. In the right frame, click Classpath, then click edit.

TIB/Adapter for Web User’s Guide Page 23

Configuring IIS with JRun 3.0

5. In the Java Classpath field, type the location of the .jar files as shown next (for
Windows NT). Note that drive c is used in the example. You should use the drive
name on which the software is installed, if it is different.
— c:/tibco/Repository/jars/TIBRepoClient32.jar
— c:/tibco/Adapter/SDK/java/Maverick32.jar
— c:/tibco/tibrv/lib/tibrvj.jar
— c:/tibco/adweb/java/taweb.jar

6. In the left frame under JRun Default Server, expand Web Applications.

You can create a new application or use the Default User Application.

Page 24 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

7. Expand Default User Application. Make sure Application Mapping is /.

8. In the left frame, under Default User Application, click Servlet Definitions.

9. Click edit to add a TAW servlet definition.

10. Change the init arguments to the parameters given next.
Name: TAW

TIB/Adapter for Web User’s Guide Page 25

Configuring IIS with JRun 3.0

Class Name: com.tibco.portal.gw.web.TAW

In Init Arguments (at right), type:

— configFile = c:/tibco/adweb/data/taw5config.dat
— debugLevel = 0
— debugSubject = taw.debug.jrun

You may want to change the arguments depending on your needs.

Click OK to apply your changes and close the dialog box. See setDebugLevel() on page
62 for more information about the debug level. See setDebugSubject() on page 64 for
more information about the debug subject.

11. Click update.

Page 26 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

12. Set the preload option for TAW by clicking set preload order.

13. Click TAW and click > to transfer it to the right.

14. Click update.

15. In the left frame, under Default User Application, click Servlet URL Mappings.

16. Click edit and type the following:

Virtual Path/Extension: /servlet/TAW

TIB/Adapter for Web User’s Guide Page 27

Configuring IIS with JRun 3.0

Servlet Invoked: com.tibco.portal.gw.web.TAW

17. Click update.

18. Restart your JRun Default Server by clicking restart server under JRun Default
Server. Your TAW servlet should be configured correctly.

Page 28 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

19. Go to Verifying Installation and Configuration on page 36 to ensure the configuration

and installation is correct.

TIB/Adapter for Web User’s Guide Page 29

Configuring iPlanet Web Server

Configuring iPlanet Web Server

If using an iPlanet web server, before sending a request to the servlet, you must configure
it with the location of the TAW .jar files and .dat (repository) file. Both tasks are done in
the Netscape Enterprise Administration Server Service Manager.

1. Invoke the Netscape Enterprise Administration Server Service Manager and

select the server to manage. Click Manage.

Page 30 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

2. The following screen appears. The server can be on or off. Click the Servlets tab to
continue.

TIB/Adapter for Web User’s Guide Page 31

Configuring iPlanet Web Server

3. The following screen appears. The Activate the Servlet Engine? option must be
selected as shown. In the navigation bar at right, click Configure JVM Attributes.

Page 32 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

4. The following screen appears.

In the Classpath: field, type the location of the .jar files separated by a colon as
shown in the previous diagram. For example:
— /tibco/Repository/jars/TIBRepoClient32.jar;
— /tibco/Adapter/SDK/java/Maverick32.jar;
— /tibco/tibrv/lib/tibrvj.jar;
— /tibco/adweb/java/taweb.jar;

TIB/Adapter for Web User’s Guide Page 33

Configuring iPlanet Web Server

5. In the navigation bar at right, click Configure Servlet Attributes. The following
screen appears:

Information must be added in the following fields:

a. Servlet Name: TAW
b. Servlet Code (class name): com.tibco.portal.gw.web.TAW

c. Servlet Classpath: <install_dir>/java/taweb.jar

d. Set the repository file, TAW debug subject and debug level (note that there is no
space after the comma). In Servlet Args:
configFile=<install_dir>/data/taw5config.dat,
debugSubject=taw.debug.iplanet,debugLevel=0

You may want to change the arguments depending on your needs. See
setDebugLevel() on page 62 for more information about setting the debug level. See
setDebugSubject() on page 64 for more information about setting the debug subject.

Page 34 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

6. In the navigation bar at right, click Configure Servlet Virtual Path

Translation. The following screen appears:

Two entries must be added:

a. In Virtual Path:, type /TAW
b. In Servlet:, type TAW
c. Click OK.
d. In Virtual Path:, type /servlet/TAW
e. In Servlet:, type TAW
f. Click OK.
7. Restart your web server.
8. Go to Verifying Installation and Configuration on page 36 to ensure the configuration
and installation was correct.

TIB/Adapter for Web User’s Guide Page 35

Verifying Installation and Configuration

Verifying Installation and Configuration

You can verify the installation and configuration by running the simple service instance.
The service returns a string value to an HTTP client when the service is called by the
client.
The following set up is used:

One command window where the service is run.

A web browser to send the request.
Start the simple service and send a request.
1. In a command window change directory to the TAW samples directory:
cd <installation_path>/samples/rv6/java
2. Edit the Makefile under the directory to reflect your current environment, then type
make or nmake (Microsoft utility).

3. Make sure that tibrvj.jar and taweb.jar are in CLASSPATH. Type the following to
start the simple service instance:
> java SimpleSvc taw.simple "Hello" and press Enter
The simple service starts and is ready to process requests. The service listens on the
taw.simple subject and returns the string "Hello" to each HTTP client that sends a
request on the taw subject.
4. In a web browser, type the following in the Location field (Netscape) or Address field
(Internet Explorer):
http://<web_server_name>/servlet/TAW?subject=taw.simple and press Enter
The servlet sends a discovery message along with its inbox on TIB/Rendezvous. The
service receives the request, processes it and returns the results to the servlet, which
returns it to the HTTP client. For example:

Page 36 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

Your web browser should return "Hello".

TIB/Adapter for Web User’s Guide Page 37

Configuring Service Instance and Servlet Parameters

Configuring Service Instance and Servlet Parameters

GUI or non GUI based HTTP clients can interact with the TAW servlet. Depending on
your client, the next sections explain how to configure the TAW servlet to provide a
different set of defaults for any or all of your service instances.

GUI Client (Web Browser)

The TIB/AdapterAdminstrator is used to configure service instances for use with the
servlet. The next diagram shows the properties that can be set using the Administrator.
For instructions on starting and using TIB/AdapterAdministrator, see the
TIB/AdapterAdminstrator User’s Guide.

Figure 4 TIB/AdapterAdminstrator

Page 38 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

You can add entries for service instances under the ServiceConfigurationData section
and configure them as needed with a response timeout and HTML files for displaying
errors. The previous diagram shows entries for two service instances, one named default
and another named foo. The entries defined for default will be used by each service
instance, unless it has a named entry. For example, the foo service instance uses its entry
rather than that defined for default.
Note: If you do not add entries to the The ServiceConfigurationData section for your
service instances, they will use the values defined in default.
The next table lists the entries that can be defined. The last three entries take a path to an
HTML file. The HTML file must be made available under the web server’s home page in a
directory that has the same name as the service instance defined in the
ServiceConfigurationData section. For example (using IIS), the service instance foo
has the directory named inetpub\wwwroot\foo.

Name Value

timeout The amount of time in seconds that can expire after which the
servlet no longer waits for a response.

timeoutURL Path to the HTML page that displays if a timeout occurs.

serviceNotUPURL Path to the HTML page that displays if the service is not up.

internalError Path to the HTML page that displays if an internal error

occurs.

Adding Entries for a Service Instance

The previous diagram shows the entries modified that will be modified n this section.
1. Start TIB/AdapterAdminstrator and logon to the repository that contains
configuration information for the servlet. The repository path name is
<taw_install_directory>/data/taw5config.dat.

2. Display the editor for the adapter instance and click the Custom tab.
3. Right-click on ServiceConfigurationData and choose New Association
Attribute. Type service instance name. A directory that uses the service name must
exist under your web servers home page directory.

TIB/Adapter for Web User’s Guide Page 39

Configuring Service Instance and Servlet Parameters

4. Right-click on the service name icon and choose New String Attribute. Type
timeout and assign a value for the timeout. The value is given in seconds.

5. Right-click on the service name icon and choose New String Attribute. Type
timeoutURL and assign a value. The value is should be the path to an HTML file that
will display if the timeout is exceeded before the service responds.
6. Right-click on the service name icon and choose New String Attribute. Type
serviceNotUPURL and assign a value. The value is should be the path to an HTML file
that will display if the service is not up.
7. Right-click on the service name icon and choose New String Attribute. Type
internalError and assign a value. The value is should be the path to an HTML file
that will display if an internal error within the service instance occurs.
8. Create and place the HTML files identified in the ServiceConfigurationData
section, under the home directory for the web server in a directory that is named with
the service instance name given in step 3.

Setting TAW Servlet Parameters

You can change the announce and heartbeat subject, the server allocation method and
additional information for the servlet. The defaults shown in the previous diagram in the
TAWConfiguration section are used, unless you modify them.

Parameter Description

TAWannounceSubject When servlet comes up, it sends a broadcast message that it

is up. The backend services must listen to this subject to
realize that the servlet is up.

TAWheartbeatSubject The servlet listens on this subject name to learn that a

backend service is actively listening.

serviceAllocation Determines which service instance will be used when a

request is made.
lru—The service instance least recently used is selected.
random—The servlet randomly allocates requests among all
service instances.
pending—The service instance that has the least number of
pending requests will be selected.

Page 40 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

Parameter Description

modifiedMessage 1—The backend service instance can query for client host
and client address. If any other value is given, the
information is not provided.

Non GUI Client

If you are using a non GUI client, only the status code and phrase is returned along with
your data payload. You should delete the timeoutURL, serviceNotUPURL and
internalError attributes, otherwise the Servlet will redirect the client to the URLs
defined for these attributes. A non GUI client may have no use for the redirection.

TIB/Adapter for Web User’s Guide Page 41

Configuring TIB/Rendezvous Parameters

Configuring TIB/Rendezvous Parameters

You can configure TAW to send messages on a non default TIB/Rendezvous service or
daemon by using TIB/AdapterAdminstrator to change the MainRvSession parameters.
See the TIB/AdapterAdministrator User’s Guide for information about performing the
following steps. The guide explains how to invoke TIB/AdapterAdministrator, find the
repository to load, and explains the TIB/Rendezvous session parameters.
1. Start TIB/AdapterAdministrator and logon to the repository that contains
configuration information for the servlet. The repository path name is
<taw_install_directory>/data/taw5config.dat.

2. In the application view panel at left, expand TIB/Adapter>taw1>defaultInstance

and double-click defaultInstance.
3. Click the Communications tab and in the session editor, double-click MainRVSession.
4. Edit the TIB/Rendezvous session parameters given in the Session editor and click OK.
5. Click File>Save and exit TIB/AdapterAdministrator.

Page 42 TIB/Adapter for Web User’s Guide

 Chapter 3 Administration

Mapping Arbitrary URLs to the Servlet

The shared object library libtawNmTrns.so is an optional component that allows an

iPlanet 4.0 web server running on Solaris to map arbitrary URLs to the servlet based upon
patterns specified using iPlanet's wildcard matching syntax. For details see the following
web page:
docs.iplanet.com/docs/manuals/enterprise/40/nsapi/0d_wildc.htm
Using this directive, you can specify one or more URL patterns that are to be intercepted
and routed through TAW. At the same time you specify what subject TAW uses to issue
the service request.
When the service instance receives the request, the HTTP information it gets reflects the
mapped URI not the original URI that was provided by the HTTP client (for example,
browser). However, the unmapped URI is available to the service instance in a new HTTP
URL parameter called originalURI.

Installation and Configuration

You should first install TAW version 5.x and verify that it is working correctly before
installing the nametrans plugin.
1. Copy the libtawNmTrns.so to a directory on your file system. We'll call the full path
to the library <pluginpath> in what follows.
2. Your web server's obj.conf file will need three additional lines:
At the beginning of the file, in the block of Init fn="load-modules" directives,
insert the following directive after changing <pluginpath> to reflect your installation.
Init fn="load-modules" funcs="tawNmTrnsInit,tawNmTrns"
shlib="<pluginpath>"

After this, but in the beginning of the file, anywhere in the block containing Init
definitions, place the Init for the nametrans plugin. This directive has parameters
that specify:
— servletURL. The complete URL, including scheme, of the servlet.
— mapN. A string containing the shexp pattern to match, followed by the TAW query
string, which at a minimum will specify the subject on which TAW should issue the
request.
For example:

TIB/Adapter for Web User’s Guide Page 43

Mapping Arbitrary URLs to the Servlet

Init fn="tawNmTrnsInit" servletURL="/servlet/TAW" map0="/foo/bar/*

subject=foo.bar" map1="/foo/baz/my* subject=foobar"

This directive routes all requests whose URLs match /foo/bar/* to TAW requests on
the subject foo.bar. URLs matching /foo/baz/my* will use the subject foobar.
Before any other NameTrans directives in the default object section (that starts with
<Object name="default">), type:

NameTrans fn="tawNmTrns"

Page 44 TIB/Adapter for Web User’s Guide

Chapter 4 Using TIB/Hawk Methods

TIB/Adapter for Web contains TIB/Hawk AMI methods that can be used to change and
display certain parameters at run-time. TIB/Hawk, an enterprise monitoring tool from
TIBCO Software Inc., monitors and manages distributed applications and systems.

Topics

Introduction, page 46

Starting TIB/Hawk Software, page 47

The Auto-Discovery Process, page 48

Invoking Microagent Methods, page 49

Available Microagents, page 52

TIB/Adapter for Web User’s Guide Page 45

Introduction

Introduction

In a TIB/Hawk environment, agents on each local computer perform the monitoring

work. A TIB/Hawk Agent is an autonomous process that uses microagents to monitor
local applications and systems activity. Microagents represent managed objects such as
operating system subsystems, log files, event logs, and applications. Each microagent
exposes a set of methods to the agent for collecting information and taking actions. This
design allows for separation between management data and management rules or
policies.
TIB/Hawk Display is an application for viewing and managing TIB/Hawk objects on
your network. The Display application is not a centralized console, but a local window
into network activity. In TIB/Hawk Display, an administrator can discover TIB/Hawk
Agents that are running, and communicate with microagents on each agent machine.
Using application menus and dialogs, administrators can also build and distribute
rulebases, which control the monitoring behavior of TIB/Hawk Agents.
For detailed information about TIB/Hawk product components, see your TIB/Hawk
Administrator’s Guide.

Page 46 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

Starting TIB/Hawk Software

The following sections describe how to start TIB/Hawk product components on Unix and
Windows NT platforms.

Starting TIB/Hawk Software on Unix

To start TIB/Hawk product components on Unix:
1. In a command window, start the TIB/Hawk Agent by typing:
startagent

2. In a new command window, set the DISPLAY environment variable for your
workstation by typing:
setenv DISPLAY <hostname>:0.0

3. Start TIB/Hawk Display by typing:

startdisplay &

After TIB/Hawk Display is started, the operation is the same on the Unix and Windows
NT platforms.

Starting TIB/Hawk Software on Windows NT

Once installed, the TIB/Hawk Agent runs as a Windows NT service. The service is
configured to start automatically. You must start the TIB/Hawk Display application on
your workstation to access the user interface.

To start an instance of TIB/Hawk Display on Windows NT:

Select Start>Programs>TIB-Hawk Software>Hawk Display, or double-click Hawk

Display in the TIB/Hawk program group.

TIB/Adapter for Web User’s Guide Page 47

The Auto-Discovery Process

The Auto-Discovery Process

After you start an instance of TIB/Hawk Display, it continually discovers machines

running TIB/Hawk Agents on your network. Container icons are created for each agent,
and arranged hierarchically in clusters. By default, agent icons are clustered according to
subnets.
At first, the Agents container is empty. Its counter displays a value of zero and, on the
right, the Discovered counter is also at zero. Both icons are initially green in color to show
that no alerts, or warning messages, are in effect. As agents are discovered, the counters
increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a

container in the left panel displays nested items on the right.
Icon colors change to reflect the highest level of alert found on discovered agents. For
explanations of icon elements and characteristics, see your TIB/Hawk Administrator’s
Guide.

Page 48 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

Invoking Microagent Methods

A set of default microagents, platform-specific and platform-independent, is loaded when

a TIB/Hawk Agent is started. When you install and start the TIB/Adapter for Web,
microagents for the adapter are dynamically added to the local agent.
The following steps describe how to invoke a microagent method by specifying a
microagent, method name, and optional method arguments.
To invoke a microagent method on a TIB/Hawk Agent:
1. In TIB/Hawk Display, right-click on the agent icon and select Get Microagents.
If TIB/Hawk security is implemented on your system and you do not have access to
microagents on this agent, an error dialog displays. Select another agent, or contact
your system administrator to obtain access.
2. The Microagents, Methods and Arguments dialog displays. The panel on the upper
left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately
returns a single set of current results. Subscribing provides updates of current results
at regular intervals. Radio buttons at the bottom of the dialog control these modes.

TIB/Adapter for Web User’s Guide Page 49

Invoking Microagent Methods

3. Click a microagent name, such as Self, to display a list of associated methods and text
descriptions in the panels below.
4. Click the name of the method to invoke, such as getComponentInfo.

If the method accepts arguments, fields for each argument display in the upper right
panel. Detailed help text displays in the lower panel.
5. Specify any arguments for the method invocation.
6. Verify that the Invoke radio button is selected.
7. Click the Invoke button to invoke the selected method.

Page 50 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

The Invocation Results dialog displays the results returned by the method.

8. Click Done to close the dialog.

These steps describe how to interactively invoke a microagent method and receive a
single set of results in TIB/Hawk Display. You can also use a microagent method as the
data source of a TIB/Hawk rule. Rules automatically receive method results, apply tests
to evaluate them, then take action if necessary. For more information on building
TIB/Hawk rules and rulebases, see your TIB/Hawk Administrator’s Guide.

TIB/Adapter for Web User’s Guide Page 51

Available Microagents

Available Microagents

Each TIB/Adapter for Web instance is represented by two TIB/Hawk microagents. One
microagent represents the adapter itself. One microagent is provided by the TIB/Adapter
for SDK product, which is used to develop TAW.

TAW5agent:<agent_id>. Monitors the adapter itself.

COM.TIBCO.ADAPTER:<agent_id>. Monitors the adapter main thread.

TAW5agent:<agent_id> Methods
The following table lists each method available for the TAW5agent:<agent_id> microagent
and page on which the method is explained.

Method Description Page

_onUnsolictedMsg() Displays alert messages sent to the current agent. 61

getDebugLevel() Returns the debug level. 56

getDebugSubject() Returns the debug subject 57

getServletContext() Returns configuration information for the servlet. 58

setDebugLevel() Sets the debug level. 62

setDebugSubject() Sets the debug subject. 64

Page 52 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

COM.TIBCO.ADAPTER.TAW:<agent_id> Methods
The following table lists each method available for the
COM.TIBCO.ADAPTER.TAW:<agent_id> microagent and page on which the method is
explained. Although the Microagents, Methods and Arguments dialog in TIB/Hawk
Display lists more methods for this microagent than are documented here, only the
following methods are supported.

Method Description Page

getComponents() Not applicable.

getConfig() Returns basic configuration information, such as the 54

repository URL, adapter instance location, and
command used to start the agent. For more detailed
information, invoke a more specific method.

getConfigProperties() Returns a list of publishers and subscribers. 55

getRvConfig() Not applicable.

getStatus() Returns general status information, such as the 59

number of TIB/Rendezvous messages received and
published, the number of errors since the last call, the
PID of the application, and more.

getTraceSinks() Not applicable.

getVersion() Returns the instance ID, adapter name, version, and 60

date for this adapter instance. Also returns version
information for the TIB/Adapter SDK, if installed.

preRegisterListener Not applicable.

reviewLedger() Not applicable.

setTraceSinks() Not applicable.

stopApplicationInstance() Not applicable.

unRegisterListener() Not applicable.

TIB/Adapter for Web User’s Guide Page 53

Available Microagents

getConfig()
COM.TIBCO.ADAPTER.TAW:<agent_id>

Purpose
Retrieves generic configuration information. More specific configuration information is
accessed through separate methods.

Parameters
None

Returns

Name Type Description

Instance ID string Instance ID of this agent.

Adapter Name string Name of the agent.

Repository string URL of the repository used for agent configuration.

Connection

Configuration string Location of the adapter repository instance; either a file

URL name or configuration URL.

Command string Command line arguments used to start the agent.

Page 54 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

getConfigProperties()
COM.TIBCO.ADAPTER.TAW:<agent_id>

Purpose
Returns all attributes and elements for the given repository object.

Parameters

Name Type Description

Property string Name of the property for which elements (tags) and
attributes are desired. For example, agentone/startup.
If no value is given, all properties are returned.

Returns

Name Type Description

Element Name string Repository directory for the property.

Attribute Name string Name of the repository object attribute.

Attribute Value string Value of the repository object attribute.

Line integer Line number in which this property is defined in the

repository instance file.

TIB/Adapter for Web User’s Guide Page 55

Available Microagents

getDebugLevel()
Taw5agent:<agent_id>

Purpose
Returns the current debug level setting.

Parameters
None

Returns

Name Type Description

DebugLevel integer The debug level:

0— No debug information displayed.
1—Configuration information is reported only to the log
file (JRun) or standard out (iPlanet).
2—Configuration information is written to a
TIB/Rendezvous message and published on the debug
subject name. A TIB/Rendezvous enabled application
can subscribe to the message.

Page 56 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

getDebugSubject()
Taw5agent:<agent_id>

Purpose
Returns the debug subject name.

Parameters
None

TIB/Adapter for Web User’s Guide Page 57

Available Microagents

getServletContext()
Taw5agent:<agent_id>

Purpose
Returns context information for the servlet.

Parameters
None

Returns

Name Type Description

Servlet Context String Returns the servlet major and minor release number and
release information about the web server on which the
servlet is installed.

Page 58 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

getStatus()
COM.TIBCO.ADAPTER.TAW:<agent_id>

Purpose
Retrieves basic status information about the adapter.

Parameters
None

Returns

Name Type Description

Instance ID string Instance ID for this adapter instance.

Adapter Name string Name of the agent.

Uptime integer Number of seconds since startup.

Messages Received integer Number of TIB/Rendezvous messages received.

Messages Sent integer Number of TIB/Rendezvous messages published.

New Errors integer Number of errors since the last call to this method.

Total Errors integer Total number of errors since startup.

Process ID integer Process ID of the application.

Host string Name of host machine on which this agent is running.

TIB/Adapter for Web User’s Guide Page 59

Available Microagents

getVersion()
COM.TIBCO.ADAPTER.TAW:<agent_id>

Purpose
Retrieves version information for the current application. Two lines may be returned, one
for the TIB/Adapter SDK, one for the adapter.

Parameters
None

Returns

Name Description

Instance ID The instance ID as a string, for example SDK.

Adapter Name Name of the agent as a string, for example agentone.

Version Version number as a string, for example 1.1.

Page 60 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

_onUnsolictedMsg()
TAW5agent:<agent_id>
COM.TIBCO.ADAPTER.TAW:<agent_id>

Purpose
Displays all alert messages sent from TAW.

Parameters
None

Returns
This method returns all alert messages if they exist or an error if not successful.

TIB/Adapter for Web User’s Guide Page 61

Available Microagents

setDebugLevel()
COM.TIBCO.ADAPTER.TAW:<agent_id>

Purpose
Set the debug level for the current service instance.

Remarks
This information is useful as an aid in the debugging process. When the debug level is set
to 2, debug information is written to a TIB/Rendezvous message and published on the
debug subject. You can invoke tibrvlisten on the debug subject to display the message.
This allows you to be sure the backend process is getting the right information and
reporting the correct information back. The debug message includes the inbound message
from the HTTP client (or web browser), outbound message to the backend service and
response from the backend service. For example:

Inbound message from HTTP client
[2000-09-27 12:45:46]: subject=taw5.debug, message={Thread-Id :
="Thread[Thread-11,5,main]" Start Time : =2000-09-27 19:47:22.675000000Z
Request Headers : ={connection="Keep-Alive" user-agent="Mozilla/4.6 [en]
(WinNT; U)" pragma="no-cache" host="vipin-l" accept="image/gif,
image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*"
accept-encoding="gzip" accept-language="en,pdf"
accept-charset="iso-8859-1,*,utf-8"} Request Parameters :
={subject="taw5listen"}

Outbound message to backend service

Outbound Message : ={^pfmt^=10 ^ver^=30 ^type^=10 HTTPmethod="GET"
HTTPuri="/servlet/TAW" HTTPversion="HTTP/1.0" URLuserName=""
URLpassword="" URLpath="/servlet" URLresource="/TAW" TAWversion="5.0"
HTTPheaders={connection="Keep-Alive" user-agent="Mozilla/4.6 [en] (WinNT;
U)" pragma="no-cache" host="vipin-l" accept="image/gif, image/x-x bitmap,
image/jpeg, image/pjpeg, image/png, */*" accept-encoding="gzip"
accept-language="en,pdf" accept-charset="iso-8859-1,*,utf-8"}
URLparameters={subject="taw5listen"}}

Response from the backend service

Inbound Message : ={^pfmt^=10 ^ver^=30 ^type^=10 HTTPstatusCode=200
HTTPreasonPhrase="OK" TAWversion=0 HTTPheaders={content-length:="14"}
^data^="listenfromtaw5"} HTTP CLIENT: ="START processReply" HttpHeaders :
="TibrvMsgField[name=HTTPheaders,id=0,type=MSG(1),data={
content-length:="14" }]" HttpReasonPhrase : ="OK" HttpStatusCode : =200
setStatus="" String message : ="listenfromtaw5" HTTP CLIENT: ="DONE
processReply" Finished Time : =2000-09-27 19:47:22.712000000Z}

Page 62 TIB/Adapter for Web User’s Guide

 Chapter 4 Using TIB/Hawk Methods

Parameter

Name Type Description

DebugLevel integer The debug level:

0— No debug information displayed.
1—Configuration information is reported only to the
log file (JRun) or standard out (iPlanet).
2—Configuration information is written to a
TIB/Rendezvous message and published on the
debug subject name. A TIB/Rendezvous enabled
application can subscribe to the message.

Returns
Returns OK if successful or an error if not successful.

TIB/Adapter for Web User’s Guide Page 63

Available Microagents

setDebugSubject()
Taw5agent:<agent_id>

Purpose
Sets the debug subject on which configuration information will be published.

Parameters

Name Type Description

debugSubject String Subject name.

Returns
Returns OK if successful or an error if not successful.

Page 64 TIB/Adapter for Web User’s Guide

Chapter 5 C++ API for TIB/Rendezvous 6.x

This chapter describes the C++ API used with TIB/Rendezvous 6.x. Use this API to write
TIB/Adapter for Web service instances when linking to TIB/Rendezvous 6.x. With this
API you can also create a service pool and use TIB/Rendezvous distributed queues or the
TAW service registry to load-balance requests to service pool members.
This chapter also includes sample source programs that illustrate how to write both
simple service instances as well as more complex RVDQ-based services.

Topics

Overview, page 66

TAWrvService, page 68

TAWrvRequest, page 83

APSvc, page 92

Compiling the Service Examples, page 104

Simple Service C++ Example, page 105

File Service C++ Example, page 108

WorldHello Service C++ Example, page 112

HelloGoodbye Service C++ Example, page 116

MultiDispatcher Service C++ Example, page 121

Simple Service Registry C++ Example, page 125

TIB/Adapter for Web User’s Guide Page 65

Overview

Overview

Use this API to write TAW service and service-pool applications. It provides the
capability to easily use TIB/Rendezvous version 6.x distributed queues or the TAW
service registry to load-balance requests to service pool members.
The TIB/Adapter for Web distribution contains sample source programs that illustrate
how to write very simple applications as well as more complex RVDQ-based services.

The Basics
Your TIB/Adapter for Web service instances must perform the following basic steps:
1. Include rv6/TAWrv.h
2. Create a subclass of TAWrvService that implements TAWrvService::onMsg(). Inside
onMsg(), arrange for one of the TAWrvRequest::reply() methods to return data to
the servlet.
3. Instantiate your TAWrvService subclass in your main program, and then call its
enableRequests() method to begin listening for requests.

The example programs, simplesvc.cc and filesvc.cc illustrate this basic structure.
They also show how to handle non-text data and manipulate HTTP reply headers.

Service Pools
In some applications, the request rate can exceed the capacity of a single service instance.
A service pool is a fault-tolerant and load-balanced collection of services.
TIB/Rendezvous Distributed Queues (RVDQ) ensure that a request is delivered to only
one pool member. The service registry API can also be used for load balancing. See
Building Service Instances on page 4 for an overview of both methods.
The TAW C++ API makes it very convenient to set up service pools. For more information
on setting up service pools, see Setting up RVDQ Service Pools on page 316.

Page 66 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Classes
There are only two classes that you need to know about to use the C++ API:

TAWrvService

TAWrvRequest
You must create your own subclass of TAWrvService. The onMsg() or onDirectMsg()
methods of this subclass will receive TAWrvRequest objects which contain all of the HTTP
information about the request as well as any data.
Use the following class to call the service registry API:

APSvc

C++ Example Service Instances for TIB/Rendezvous 6.x

This section explains the sample source programs that illustrate how to write both simple
service instances as well as more complex RVDQ-based services.
Six example C++ programs are provided with TIB/Adapter for Web:

simplesvc.cc. This is a glorified Hello World program that allows you to specify the
subject the service will listen for requests on, and the string it will return. See Simple
Service C++ Example on page 105 for details.

filesvc.cc. This shows how to transmit string or binary data and set HTTP reply
headers. See File Service C++ Example on page 108 for details.

worldhello.cc. This is a service pool example. Depending on the command line
argument given, the service will return a language-specific greeting. See WorldHello
Service C++ Example on page 112 for details.

hellogoodbye.cc. This is another service pool example. This shows how an initial
request can be directed to a worker service by the RVDQ scheduler, and how the
direct request subject is used to bypass the RVDQ scheduler for subsequent requests
from the same client. See HelloGoodbye Service C++ Example on page 116 for details.

multiDispatcher.cc. This example illustrates how to create more than one
dispatcher thread to dispatch events from the queue. Typically one dispatcher thread
is used to dispatch events. By creating multiple dispatcher threads, it allows multiple
requests to be processed simultaneously. See MultiDispatcher Service C++ Example
on page 121 for details.

simplesvcReg.cc. This example demonstrates the service registry functionality of the
servlet. See Simple Service Registry C++ Example on page 125 for details.

TIB/Adapter for Web User’s Guide Page 67

TAWrvService

TAWrvService
RV 6.x only
Class

Purpose
TAWrvService is an abstract class. Your application needs to create a subclass of
TAWrvService that implements the request callbacks that will be invoked when requests
are received.

Remarks
There are two constructors. The first constructor is used to build standard,
non-load-balancing service instances, using a TibrvTransport. The second constructor is
used to build load-balancing service instances based on TIB/Rendezvous distributed
queues, using a TibrvCmQueueTransportQueue. If directSubject is specified, requests
may be sent directly to this service instance using that subject, bypassing the RVDQ
scheduler.

Member Summary

Name Description Page

TAWrvService::TAWrvService() Constructor 70

TAWrvService::~TAWrvService() Destructor 72

TAWrvService::disableRequests() Stop listening requests 73

TAWrvService::enableRequests() Start listening for requests 74

TAWrvService::fence() Blocks the program 75

TAWrvService::get...() Accessors Acessor methods 76

TAWrvService::isEnabled() Return true if requests are 77

enabled

TAWrvService::isValid() Return true if this TAWrvSession 78

object is valid

Page 68 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Name Description Page

TAWrvService::onDirectMsg() Invoked in response to requests 79

received on the direct request
subject.

TAWrvService::onMsg() Invoked in response to requests 80

received on the standard request
subject.

TAWrvService::setDirectRequestSub Set subject associated with 81

ject()
onDirectMsg()

TAWrvService::setRequestSubject() Set subject associated with 82

onMsg()

TIB/Adapter for Web User’s Guide Page 69

TAWrvService

TAWrvService::TAWrvService()
RV 6.x only
Constructor

Declaration
TAWrvService(TibrvTransport* pRvTransport,
TibrvQueue* pQueue = 0,
const char* requestSubject=0,
const char* directRequestSubject=0);
TAWrvService(TibrvCmQueueTransport* pRvCmqTransport,
TibrvQueue* pQueue = 0,
const char* requestSubject=0,
const char* directRequestSubject=0);

Purpose
All applications must provide a subclass of TAWrvService that implements the onMsg
method. The first constructor is used to setup normal reliable communications between
the servlet and your application. The second constructor is used to build RVDQ-based
service pools.

Remarks
Subjects need not be specified here, but must be set prior to enabling the service.

Parameters

Name Description

pRvTransport Optional TIB/Rendezvous reliable transport to use. If

none is specified, a default TibrvTransport will be
constructed.

pRvCmqTransport TIB/Rendezvous distributed queue transport

(TibrvCmQueueTransport) to use.

pQueue The TIB/Rendezvous queue to use. If not specified, the

default TIB/Rendezvous queue associated with the
TIB/Rendezvous daemon is used.

requestSubject Subject name that the application will be listening for

requests on. All RVDQ-based service pool members listen
to this subject, but RVDQ guarantees delivery to only one
member.

Page 70 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Name Description

directRequestSubject For RVDQ-based applications, this is a secondary subject

name used to provide direct access to a service pool
member.

Example
class SimpleService : public TAWrvService
{
public:
SimpleService(TibrvTransport *pRvTransport, TibrvQueue *pQueue,
const char* requestSubject, const char* replyString)
: TAWrvService(pRvTransport, pQueue, requestSubject),
_replyString(replyString){};
~SimpleService(){};
void onMsg(TAWrvRequest* pRequest);
private:
const char* _replyString;
};

Errors
Use the isValid() member to make sure that the constructor did not fail. For a
descriptive error message string, use the getErrorMsg() member.

See Also
TAWrvService::isValid(), page 78.
getErrorMsg(), page 76.

TIB/Adapter for Web User’s Guide Page 71

TAWrvService

TAWrvService::~TAWrvService()
RV 6.x only
Destructor

Declaration
~TAWrvService();

Purpose
This method destroys the TAWrvService instance from which it is called and releases all
resources.

Remarks
This destructor must be called whenever you are finished with communications between
the servlet and your application.

Page 72 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvService::disableRequests()
RV 6.x only
Method

Declaration
virtual tibrv_bool disableRequests();

Purpose
Stop listening for requests.

Remarks
This method destroys the TibrvListener objects created in enableRequests().

Parameters
Returns TIBRV_TRUE if successful, TIBRV_FALSE otherwise.

TIB/Adapter for Web User’s Guide Page 73

TAWrvService

TAWrvService::enableRequests()
RV 6.x only
Method

Declaration
virtual tibrv_bool enableRequests();

Purpose
Start listening for requests.

Remarks
Prior to invoking enableRequests(), you must set the subjects on which your service
will accept requests. You can do this in the constructor, or use the setRequestSubject()
and setDirectRequestSubject(). This method creates the TibrvListener objects
that remain valid until the disableRequests() method is invoked.

Parameters
Returns TIBRV_TRUE if successful, TIBRV_FALSE otherwise.

See Also
TAWrvService::setRequestSubject(), page 82.
TAWrvService::setDirectRequestSubject(), page 81.
TAWrvService::disableRequests(), page 73.

Page 74 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvService::fence()
RV 6.x only
Method

Declaration
virtual void fence();

Purpose
The fence() method is used to block the program.
If the method is not used, the main program will exit, preventing the dispatcher thread
from doing its job (a dispatcher thread is created to listen on the request subject). You
might want to override the method to block the main application and allow its thread to
service, while exit and do clean up under a special condition.

TIB/Adapter for Web User’s Guide Page 75

TAWrvService

TAWrvService::get...() Accessors
RV 6.x only
Method

Declaration
virtual const char* getDirectRequestSubject();
TibrvQueue* getDispatchQueue();
virtual const char* getErrorMsg();
virtual const char* getRequestSubject();
const TibrvCmQueueTransport* getTibrvCmQueueTransport();
const TibrvTransport* getTibrvTransport();

Purpose
Accessor methods for TAWrvService instances.

Name Description

getDirectRequestSubject() Returns the secondary subject used by RVDQ-based

services to listen for requests that bypass RVDQ
load-balancing or null.

getDispatchQueue() Return the event queue in use.

getErrorMsg() Returns the error message for an invalid service.

getRequestSubject() Returns the subject used for reliable or RVDQ-based

requests. This subject is used by both RVDQ-based pooled
services, or by singleton applications.

getTibrvCmQueueTransport() Returns the TIB/Rendezvous distributed queue transport in

use.

getTibrvTransport() Returns the TIB/Rendezvous reliable transport in use.

Page 76 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvService::isEnabled()
RV 6.x only
Method

Declaration
virtual tibrv_bool isEnabled();

Purpose
Determine whether the service is currently listening for requests.

Parameters
Returns TIBRV_TRUE if the service is currently listening for requests, TIBRV_FALSE
otherwise.

TIB/Adapter for Web User’s Guide Page 77

TAWrvService

TAWrvService::isValid()
RV 6.x only
Method

Declaration
virtual tibrv_bool isValid();

Purpose
Provide a way for the TAWrvService constructor to report that it failed.

Remarks
Use the getErrorMsg() to determine the reason for the failure.

Parameters
Returns TIBRV_TRUE if the object could be correctly built, TIBRV_FALSE otherwise.

See Also
getErrorMsg(), page 76.

Page 78 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvService::onDirectMsg()
RV 6.x only
Method

Declaration
virtual void onDirectMsg(TAWrvRequest* pRvRequest);

Purpose
This method is only relevant to RVDQ-based service instances. This method is called
when a request is received on the direct request subject. Requests to direct request
subjects are not intercepted by the RVDQ scheduler. The default implementation merely
invokes the onMsg() method.

Parameters

Name Description

pRvRequest Pointer to the TAWrvRequest object that encapsulates all data,

header and return address information associated with the
request.

TIB/Adapter for Web User’s Guide Page 79

TAWrvService

TAWrvService::onMsg()
RV 6.x only
Method

Declaration
virtual void onMsg(TAWrvRequest* pRvRequest) = 0;

Purpose
All applications must provide a subclass of TAWrvService that implements the onMsg
method. This method is called when a request is received.

Parameters

Name Description

pRvRequest Pointer to the TAWrvRequest object that encapsulates all data,

header and return address information associated with the
request.

Page 80 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvService::setDirectRequestSubject()
RV 6.x only
Method

Declaration
virtual void setDirectRequestSubject(const char* subject);

Purpose
Set the subject name used to listen for requests directed at a specific member or members
of an RVDQ-based service pool. RVDQ-based applications can use this subject to get
requests without the intervention of the RVDQ scheduler.

Parameters

Name Description

subject TIB/Rendezvous subject name that the service will use to

listen for direct requests.

TIB/Adapter for Web User’s Guide Page 81

TAWrvService

TAWrvService::setRequestSubject()
RV 6.x only
Method

Declaration
virtual void setRequestSubject(const char* subject);

Purpose
Set the subject name used to listen for requests. This subject is used by both RVDQ-based
pooled services, or by singleton applications.

Parameters

Name Description

subject TIB/Rendezvous subject name that the service will use to

listen for requests.

Page 82 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvRequest
RV 6.x only
Class

Purpose
TAWrvRequest objects are manufactured when requests are received. They encapsulate all
of the HTTP information in the request, including the communication endpoint to reply
to. Members can be used to access HTTP request information, as well as to prepare a
reply.

Remarks
These objects are created and destroyed by the API and are valid for the duration of one
invocation of your application’s implementation of TAWrvService::onMsg(). You must
copy any data or header information if your application will need them after onMsg()
returns.

Member Summary

Name Description Page

TAWrvRequest::TAWrvRequest() Constructor 84

TAWrvRequest::get...() Accessor Methods 85

Accessors

TAWrvRequest::isValid() Tests object validity. Useful for 88

detecting failures during a
TAWrvRequest constructor.

TAWrvRequest::reply() Marshall reply and send to servlet. 89

TAWrvRequest::set...() Sets a value for TAWrvRequest 90

instances.

TIB/Adapter for Web User’s Guide Page 83

TAWrvRequest

TAWrvRequest::TAWrvRequest()
RV 6.x only
Constructor

Declarations
TAWrvRequest(TibrvMsg& rRvMsg, TibrvTransport *pRvTransport);

Purpose
Sets up an object that is used to respond to a request.

Parameters

Name Description

rRvMsg Incoming TibrvMsg (from a listener callback).

pRvTransport Transport to use in the reply.

Page 84 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvRequest::get...() Accessors
RV 6.x only
Methods

Declarations
// ----------------- Request ------------------
const char* getHttpHeader(const char* name);
const TibrvMsg& getHttpHeaders();
const char* getHttpMethod();
const char* getHttpUri();
const char* getHttpVersion();
const char* getProtocolVersion();
const char* getUrlParameter(const char* name);
const TibrvMsg& getUrlParameters();
const char* getUrlPath();
const char* getUrlResource();

// ----------------- Reply ------------------

const char* getHttpReplyHeader(const char* name);
const TibrvMsg& getHttpReplyHeaders();
const void* getHttpReplyOpaqueEntityBody(unsigned int& rLen);
const char* getHttpReplyReasonPhrase();
int getHttpReplyStatusCode();
const char* getHttpReplyStringEntityBody(unsigned int& rLen);
const char* getReplyProtocolVersion();

Purpose
Accessors for TAWrvRequest instances.

Request Accessors Description

getHttpHeader(name) Returns an individual request header value by name,

given the header name. The lookup is case insensitive.
If multiple values are associated with headers of the server
name, only one value will return. Use getHttpHeaders() to
manually get all the values for this call.
name—String. Name of header to get.
Returns: NULL if not found.

getHttpHeaders() Returns all of the HTTP request headers. It returns a

TibrvMsg containing one field for each header.

TIB/Adapter for Web User’s Guide Page 85

TAWrvRequest

Request Accessors Description

getHttpMethod() Returns the HTTP method from the HTTP request line.
Returns: NULL if not found.

getHttpUri() Returns the HTTP URI from the HTTP request line.
Returns: NULL if not found.

getHttpVersion() Returns the HTTP version from the HTTP request line.
Returns: NULL if not found.

getProtocolVersion() Returns the TAW version number.

getUrlParameter(name) Returns the value of a given individual query parameter

from the URL on the request line by name. The lookup is
case sensitive.
name—String. Query parameter from the URL.
Returns: NULL if not found.

getUrlParameters() Returns all query parameters from the URL on the request
line. It returns a TibrvMsg containing one field for each
parameter.

getUrlPath() Returns the path from the HTTP request line.

Returns: NULL if not found.

getUrlResource() Returns the resource from the HTTP request line.

Returns: NULL if not found.

Page 86 TIB/Adapter for Web User’s Guide


Reply Accessors
getHttpReplyHeader(name)
getHttpReplyHeaders()
getHttpReplyOpaqueEntityBody
(rLen)
getHttpReplyReasonPhrase()
getHttpReplyStatusCode()
getHttpReplyStringEntityBody(r
Len)
getReplyMsg()
getReplyProtocolVersion()
TIB/Adapter for Web User’s Guide
Chapter 5 C++ API for TIB/Rendezvous 6.x
Description
Returns the object for a given Http Header, given the name
of field to get. The look up is case insensitive.
If multiple values are associated with headers of the server
name, only one value will return. Use
getHttpReplyHeaders() to manually get all the values for
this call.
name—Char*. Name of field to get.
Returns: NULL if not found.
Returns the current set of Http Headers. It returns a
TibrvMsg containing one field for each header
Returns the binary data in the reply entity body.
rLen—The size of the entity body.
Returns the status phrase that was set.
Returns the status code that was set.
Returns the string data in the reply entity body.
rLen—The size of the entity body.
Returns the TibrvMsg reply message after reply() is called.
This method is used for debugging to verify that the
message is constructed as desired.
Returns the TAW version number.
Page 87
TAWrvRequest

TAWrvRequest::isValid()
RV 6.x only
Method

Declaration
tibrv_bool isValid();

Purpose
Tests object validity. Useful for detecting failures during a TAWrvRequest constructor.
This method is typically not used because TAWrvRequest is constructed internally.

Parameters
None.

Example
TAWrvRequest* pRequest = new TAWrvRequest(msg, pImpl->_pRvTransport);

if(!pRequest->isValid())
{
pImpl->_errorMsg = "Bad request data";
#if DEBUG
printf("TAWrvServiceRequestCallback::onMsg %s\n", pImpl->_errorMsg);
printf("\n");
#endif
}
else
pImpl->_rTAWrvService.onMsg(pRequest);
delete pRequest;
}

Page 88 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

TAWrvRequest::reply()
RV 6.x only
Method

Declaration
tibrv_bool reply();
tibrv_bool reply(const void* entityBody,
unsigned int entityBodyLen,
int statusCode = 200,
const char* reasonPhrase = "OK");

tibrv_bool reply(const char* entityBody,

int statusCode = 200,
const char* reasonPhrase = "OK");

Purpose
These methods marshall parameters from the TAWrvRequest into an TibrvMsg and send
them back to the requesting servlet. The first form assumes that all reply headers and data
have been stored using TAWrvRequest set methods. The remaining two forms are for
convenience. The second form is for sending binary data, and the third form is for sending
strings. Make sure you have the correct argument datatypes that match the parameter
datatypes.

Parameters

Name Description

entityBody The desired reply entity body. Either a string or buffer of binary
data, depending on whether entityBodyLen is specified.

entityBodyLen The length of binary data buffer.

statusCode The HTTP status code.

reasonPhase The HTTP reason phrase.

TIB/Adapter for Web User’s Guide Page 89

TAWrvRequest

TAWrvRequest::set...()
RV 6.x only
Methods

Declarations
void setHttpReplyHeader(const char* name, int value);
void setHttpReplyHeader(const char* name, const char* value);
void setHttpReplyOpaqueEntityBody(const void* body, unsigned int
bodyLen);
void setHttpReplyReasonPhrase(const char* phrase);
void setHttpReplyStatus(int code, const char* phrase);
void setHttpReplyStatusCode(int code);
void setHttpReplyStringEntityBody(const char* body);

Purpose
Sets a value for TAWrvRequest instances.

Name Description

setHttpReplyHeader(name value) Sets the value of a named HTTP header to a value.

Any preexisting value for that header is appended.
name—string. Header name
value—int. Value of header
—or—
value—string. Value of header

setHttpReplyOpaqueEntityBody Sets string data into the HTTP entity body (i.e. data
(body, bodyLen) payload) of the reply.
body—void*. Binary payload data
bodyLen—The number of bytes in the body.

setHttpReplyReasonPhrase(phrase) Sets the reply HTTP reason phrase that should

accompany the status code.
phrase—string. HTTP reason phrase

setHttpReplyStatus(code, Sets the reply status code.

phrase) code—int. HTTP reply status code
phrase—string. HTTP reason phrase

setHttpReplyStatusCode(code) Sets the reply HTTP status code.

code—int. HTTP status code

Page 90 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Name Description

setHttpReplyStringEntityBody Sets binary data into the HTTP entity body (that is,
(body) data payload) of the reply.
body—string. Payload data.

TIB/Adapter for Web User’s Guide Page 91

APSvc

APSvc
RV 6.x only
Class

Purpose
The APSvc class implements the heartbeat protocol interface.

Member Summary

Name Description Page

APSvc::APSvc() Constructor 93

~APSvc() Destructor

APSvc::appendToHeartbeat() Called just before a heartbeat is emitted. 94

APSvc::disable() Inform all service instances this service 95

instance is unable to receive requests.

APSvc::enable() Inform all service instance this service is 96

ready to receive requests.

APSvc::init() Initialize the service instance. 97

APSvc::onMsg() Process inbound messages. 98

APSvc::onTimer() Process timer events. 99

APSvc::sendHeartbeat() Respond to an announcement request by 100

sending a heartbeat.

APSvc::start() Starts sending heartbeats on the network. 101

APSvc::startHeartbeating() Starts sending periodic heartbeats by 102

activating a timer.

APSvc::terminate() Notify all APSvcRegistry instances that this 103

service instance has exited.

Page 92 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

APSvc::APSvc()
RV 6.x only
Constructor

Declaration
APSvc(const char* serviceName,
const char* requestSubject,
TibrvTransport *pHeartbeatTransport,
const char* heartbeatSubject,
double heartbeatInterval,
double failureTolerance,
const char* registrySubject,
tibrv_i8 readyStatus);

Purpose
Create a service registry instance.

Parameters

Name Description

serviceName Service name.

requestSubject A globally unique subject (inbox) for the service instance.

pheartbeatTransport TIB/Rendevous transport to be used by the heartbeat

protocol.

heartbeatSubject Subject on which heartbeats are published.

heartbeatInterval The number of seconds between heartbeats.

failureTolerance The number of seconds to wait for a heartbeat before marking

this service instance as terminated.

registrySubject Subject on which APSvcRegistry announcements are sent.

readyStatus One of: enabled, disabled, or terminated as specified in

rv6/APSvc.h.

TIB/Adapter for Web User’s Guide Page 93

APSvc

APSvc::appendToHeartbeat()
RV 6.x only
Method

Declaration
virtual TibrvMsg* appendToHeartbeat();

Purpose
The method is called just before a heartbeat is emitted.
The method returns a TibrvMsg containing auxiliary information. The method allows you
to append any auxiliary information to be associated with this service instance on the
client’s APSvcRegistry by overriding this method. The current implementation just
returns NULL.

Page 94 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

APSvc::disable()
RV 6.x only
Declaration
void disable();

Purpose
Inform all APSvcRegistry instances that this service instance is temporarily disabled and
unable to receive requests.

TIB/Adapter for Web User’s Guide Page 95

APSvc

APSvc::enable()
RV 6.x only
Declaration
void enable();

Purpose
Informs all APSvcRegistry instances that this service instance is ready to receive
requests.

Page 96 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

APSvc::init()
RV 6.x only
Method

Declaration
void init(const char* serviceName,
const char* requestSubject,
TibrvTransport *pHeartbeatTransport,
const char* heartbeatSubject,
double heartbeatInterval,
double failureTolerance,
const char* registrySubject,
tibrv_i8 readyStatus);

Purpose
Initialize a service registry instance .
Parameters

Name Description

serviceName Service name.

requestSubject A globally unique subject (inbox) for the service instance.

pheartbeatTransport TIB/Rendevous transport to be used by the heartbeat

protocol.

heartbeatSubject Subject on which heartbeats are published.

heartbeatInterval The number of seconds between heartbeats.

failureTolerance The number of seconds to wait for a heartbeat before marking

this service instance as terminated.

registrySubject Subject on which APSvcRegistry announcements are sent.

readyStatus One of: enabled, disabled, or terminated

TIB/Adapter for Web User’s Guide Page 97

APSvc

APSvc::onMsg()
RV 6.x only
Declaration
void onMsg(TibrvListener *listener, TibrvMsg& msg);

Purpose
Respond to an announcement message from an APSvcRegistry by sending a heartbeat.
This method is implemented for the abstract class TibrvMsgCallback. It will be called
when there is an incoming message with the request subject. You need not call this
method.
Parameters

Name Description

listener This parameter receives the listener event.

msg This parameter receives the inbound message.

Page 98 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

APSvc::onTimer()
RV 6.x only
Declaration
void onTimer(TibrvTimer *timer);

Purpose
Process timer events.
This method is implemented for the abstract class TibrvTimerCallback. It will be called
when there is a timer event. You need not call this method.
Parameter

Name Description

timer This parameter receives the timer event.

TIB/Adapter for Web User’s Guide Page 99

APSvc

APSvc::sendHeartbeat()
RV 6.x only
Declaration
void sendHeartbeat();

Purpose
Send a heartbeat, called internally, by responding to an announcement message from an
APSvcRegistry. You can invoke this method to explicitly send a heartbeat.

Page 100 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

APSvc::start()
RV 6.x only
Method

Declaration
void start();

Purpose
Starts sending heartbeats on the network so the registry service can recognize that the
service instance is running. This method must be invoked after this class instance is
created.

TIB/Adapter for Web User’s Guide Page 101

APSvc

APSvc::startHeartbeating()
RV 6.x only
Declaration
void startHeartbeating();

Purpose
Starts sending periodic heartbeats by activating a timer. The method is normally called by
APSvc::start() and not typically called directly. This call should be invoked only after a
service instance is disabled and then enabled.

Page 102 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

APSvc::terminate()
RV 6.x only
Declaration
void terminate();

Purpose
Informs all APSvcRegistry instances that this service instance has exited.

TIB/Adapter for Web User’s Guide Page 103

Compiling the Service Examples

Compiling the Service Examples

You must create the service example executables:

1. cd <install_path>/samples/rv6/cpp

2. Edit the Makefile to reflect your environment.

3. Type make or nmake (Microsoft utility).
4. This will make the executables for all the following examples.

Page 104 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Simple Service C++ Example

This example emulates a simple service that given a subject name and string, returns the
string in a web browser that is invoked with the subject name.

Starting the Program

Start the program from the command line. For example:
> simplesvc my.test.simplesvc hello

If /servlet/TAW is the URL mapping in your web browser type:

http://<your web server>/servlet/TAW?subject=my.test.simplesvc

The program will return a page containing hello to your web browser and the reply
message that it is sending to the servlet on the command line.

Source Code
The simplesvc.cc file where the simple service is defined is listed next. In the code, the
basic steps are to:

Derive a subclass from TAWrvService that provides an implementation of the abstract
method onMsg().

Define the onMsg() method so it is invoked by TAW whenever a request is received.
This implementation returns the string specified on the command line when the
program was invoked to the client.

Create an instance of SimpleService that uses command line parameters to
determine what subject to accept requests on, and what string to return in response to
a request.

Check that your TAWrvService subclass is valid before proceeding further. The
isValid() method is used for this purpose. If the object is not valid, the reason may
be determined by invoking the getErrorMsg() method.

Start request processing.

TIB/Adapter for Web User’s Guide Page 105

Simple Service C++ Example

simplesvc.cc
#include "rv6/TAWrv.h"
#include "stdlib.h"
#include "string.h"

// Derive a subclass from TAWrvService that provides an implementation of

// the abstract method onMsg().

class SimpleService : public TAWrvService

{
public:
SimpleService(TibrvTransport *pRvTransport, TibrvQueue *pQueue,
const char* requestSubject, const char* replyString)
: TAWrvService(pRvTransport, pQueue, requestSubject),
_replyString(replyString){};
~SimpleService(){};
void onMsg(TAWrvRequest* pRequest);
private:
const char* _replyString;
};

// onMsg() is invoked when a request is received. The string specified on

// the command line when the program was invoked is returned to the
// client.

void
SimpleService::onMsg(TAWrvRequest* pRequest)
{
const char* buf;

pRequest->reply(_replyString);

// to show the message reply function actually constructs before

// sending to the network,
// have the copy constructor copes data to msg
TibrvMsg msg = pRequest->getReplyMsg();
msg.convertToString(buf);
printf ("Reply Message: %s\n", buf);
}

int main(int argc, char** argv)

{
if(argc < 3)
{
printf("usage: %s <listen subject> <reply string>\n", argv[0]);
exit(-1);
}
char* subject = argv[1];
char* replyString = argv[2];

TibrvStatus status;

Page 106 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

printf("listening on: %s\nreplying with: \"%s\"\n",

subject, replyString);
if ( (status = Tibrv::open()) != TIBRV_OK) {
printf ("cannot open internal machinery : %s.\n", status.getText());
exit(-1);
}

// Create an instance of SimpleService that uses command line

// parameters to determine the subject to accept requests on
// and the string to return in response to a request.

SimpleService simpleService((TibrvTransport*)0, (TibrvQueue*)0,

subject, replyString);

// Make sure your subclass is valid before proceeding further

if(!simpleService.isValid())
{
printf("TAWrvService constructor failed - %s\n",
simpleService.getErrorMsg());
exit(-1);
}

// Start listening for requests

if(! simpleService.enableRequests() ) {
printf("Unable to enable request processing - %s\n",
simpleService.getErrorMsg());
}
else {
simpleService.fence(); // wait forever...
}

return 0;
}

TIB/Adapter for Web User’s Guide Page 107

File Service C++ Example

File Service C++ Example

This example emulates a simple service that shows how to transmit string or binary data
and set HTTP reply headers.

Starting the Program

Start the program from the command line. For example, if /foo/bar.gif is a gif image
file, you can run:
> filesvc my.test.filesvc /foo/bar.gif image/gif

If /servlet/TAW is the URL mapping in your web browser type:

http://<your web server>/servlet/TAW?subject=my.test.filesvc
The program will return the gif image file to your browser.

Source Code
The filesvc.cc file where the simple service is defined is given next. In the code, the
basic steps are to:

Derive a subclass from TAWrvService that provides an implementation of the
abstract method onMsg(). The method is invoked by TAW whenever a request is
received. This implementation returns the file specified on the command line and
adds the “content-type” HTTP header value that was also specified on the command
line.

Create an instance of FileService that uses command line parameters to determine
what subject to accept requests on, which file to return, and the HTTP content-type.

Check that your TAWrvService subclass is valid before proceeding further. The
isValid() method is used for this purpose. If the object is not valid, the reason may
be determined by invoking the getErrorMsg() method.

Start request processing.

Page 108 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

filesvc.cc
#include "rv6/TAWrv.h"
#include "stdlib.h"
#include "string.h"

const char* binaryExts[] =

{
".gif",
".jpg",
0
};

int isBinaryFile(const char* fileName)

{
int len = ::strlen(fileName);
char *p = (char*)fileName + (len - 4);
for(int i=0; binaryExts[i] ; i++)
{
if(strcmp(binaryExts[i], p) == 0)
return 1;
}
return 0;
}

// Derive a subclass from TAWrvService that provides an implementation of

// the abstract method onMsg()
class FileService : public TAWrvService
{
public:
FileService(TibrvTransport *pRvTransport, TibrvQueue *pQueue,
const char* requestSubject, const char* filePath,
const char* contentType);
~FileService();
void onMsg(TAWrvRequest* pRequest);
private:
const char* _filePath;
const char* _contentType;
void* _data;
tibrv_u32 _ dataLen;
tibrv_i32 _ dataRvmsgType;
};

// Create an instance of FileService

FileService::FileService(TibrvTransport *pRvTransport, TibrvQueue
*pQueue, const char* requestSubject, const char* filePath, const char*
contentType)
: TAWrvService(pRvTransport, pQueue, requestSubject),
_filePath(filePath), _contentType(contentType),
_data(0), _dataLen(0), _dataRvmsgType(TIBRVMSG_STRING)
// Open in read and binary mode
{
FILE* fp = fopen( _filePath, "rb" );

TIB/Adapter for Web User’s Guide Page 109

File Service C++ Example

if(!fp)
{
printf("Unable to open \"%s\" for reading\n", _filePath);
exit(-1);
}

unsigned int bufSize;

if (fseek(fp, 0, SEEK_END) != 0) {
printf ("Unable to determine size of file %s\n", _filePath);
exit(-1);
}
unsigned int bytesRead;
// Determine the size of the file
bufSize = ftell(fp);

if (fseek(fp, 0, SEEK_SET) != 0) {
printf ("Unable to seek to front of the file %s\n", _filePath);
exit(-1);
}
_data =(unsigned char*) malloc(bufSize * sizeof(char));
bytesRead = fread(_data, sizeof(char), bufSize, fp);

if (bufSize != bytesRead) {
printf ("size of file %d not equal to bytes readed %d\n", bufSize,
bytesRead);
exit(-1);
}

fclose(fp);
_dataLen = bufSize;

if(isBinaryFile(filePath))
{
_dataRvmsgType = TIBRVMSG_OPAQUE;
}
}

void
FileService::onMsg(TAWrvRequest* pRequest)
{
pRequest->setHttpReplyHeader("content-type", _contentType);
if(_dataRvmsgType == TIBRVMSG_STRING)
{
pRequest->reply((char*)_data);
}
else if(_dataRvmsgType == TIBRVMSG_OPAQUE)
{
pRequest->reply(_data, _dataLen);
}
}

FileService::~FileService()

Page 110 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

{
if(_data)free(_data);
}

int main(int argc, char** argv)

{

if(argc < 4)
{
printf("usage: %s <listen subject> <file path> <content-type>\n",
argv[0]);
exit(-1);
}
char* subject = argv[1];
char* filePath = argv[2];
char* contentType = argv[3];

printf("listening on: %s\nreplying with contents of: \"%s\"\nwith

response header \"content-type: %s\"\n", subject, filePath, contentType);

TibrvStatus status;

if ((status = Tibrv::open()) != TIBRV_OK) {

printf("cannot open internal machinery : %s.\n", status.getText());
exit(-1);
}

// Instantiate FileService and have constructor set a transport object

// and the default event queue
FileService fileService((TibrvTransport*)0, (TibrvQueue*)0,
subject, filePath, contentType);
// Check if FileService is a valid service
if(!fileService.isValid())
{
printf("TAWrvService constructor failed - %s\n",
fileService.getErrorMsg());
exit(-1);
}
// Start listening for requests
if(! fileService.enableRequests() ) {
printf("Unable to enable request processing - %s\n",
fileService.getErrorMsg());
}
else {
fileService.fence(); // wait forever
}

return 0;
}

TIB/Adapter for Web User’s Guide Page 111

WorldHello Service C++ Example

WorldHello Service C++ Example

This is a service pool example. Depending on the command line argument given, the
service will return a language-specific greeting. If you run multiple instances of this
service, each replying in a different language, requests will be randomly distributed to
worker services by the RVDQ scheduler, and you will see greetings in different languages
if you make multiple requests.

Starting the Program

Start multiple instances of this program from the command line. For example:
> worldhello 0 &
> worldhello 1 &
> worldhello 2 &

This runs three instances in the background. The listen subject, taw.worldhello is
hardcoded into the program.
If /servlet/TAW is the URL mapping in your web browser type:
http://<your web server>/servlet/TAW?subject=taw.worldhello
Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser.

Source Code
The worldhello.cc file where the service pool is defined is given next. In the code, the
basic steps are to:

Derive a subclass from TAWrvService that provides an implementation of the abstract
method onRequest.

Invoke the onMsg() method whenever a request is received. This implementation
returns a greeting in either Japanese, English, or French according to command line
arguments.

Provide a properly initialized TibRvCmQueueTransport to your constructor.

These four parameter definitions determine how RVDQ decides when to promote a
worker to scheduler. See the TIB/Rendezvous documentation for more details on
these parameters.

Page 112 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Create an instance of WorldHelloService that uses a command line argument to

determine which language translation of hello should be returned.

After instantiating your TAWrvService subclass, you should make sure that it is valid
before proceeding further. The isValid method is used for this purpose. If the object
is not valid, the reason may be determined by invoking the getErrorMsg method.

Start request processing.

worldhello.cc
#include "rv6/TAWrv.h"
#include "stdlib.h"
#include "stdio.h"

#define RVDQ_LISTEN_SUBJECT "taw.worldhello"

#define RVDQ_SERVICE_POOL "worldhello"

const char* greetings[] = { "Hello", "Bon jour", "Konnichiwa", 0 };

#define NUMGREETINGS 3

/* Define a RVDQ-based service */

class WorldHelloService : public TAWrvService
{
public:

WorldHelloService(TibrvCmQueueTransport *pRvCmqTransport,
TibrvQueue *pQueue,
const char* requestSubject,
int iGreetingNumber);
~WorldHelloService(){};
void onMsg(TAWrvRequest* pRequest);

protected:
int _iGreetingNumber;
};

WorldHelloService::WorldHelloService(TibrvCmQueueTransport
*pRvCmqTransport, TibrvQueue *pQueue, const char* requestSubject, int
iGreetingNumber)
: TAWrvService(pRvCmqTransport, pQueue, requestSubject)
{
_iGreetingNumber = iGreetingNumber % NUMGREETINGS;
}

void
WorldHelloService::onMsg(TAWrvRequest* pRequest)
{
char buf[512];

TIB/Adapter for Web User’s Guide Page 113

WorldHello Service C++ Example

sprintf(buf, "<html><body><h2>%s</body></html>",
greetings[_iGreetingNumber]);
pRequest->setHttpReplyHeader("content-type","text/html");
pRequest->reply(buf);
};

int main(int argc, char** argv)

{
if( argc < 2 )
{
printf("usage: %s <language index>\n", argv[0]);
exit(-1);
}
int gNum = atoi(argv[1]);

// If environment variables are not specified, default services are used

char* rvService = getenv("SERVICE"); // default rendezvous service
char* rvNetwork = getenv("NETWORK");// default primary network interface
char* rvDaemon = getenv("DAEMON"); // default local daemon on TCP 7500

TibrvStatus status;

if ((status = Tibrv::open()) != TIBRV_OK) {

printf ("cannot open internal machinery : %s.\n", status.getText());
exit(-1);
}

TibrvNetTransport rvTransport;
if ((status = rvTransport.create(rvService, rvNetwork, rvDaemon)) !=
TIBRV_OK) {
printf ("cannot create TibrvNetTransport : %s.\n", status.getText());
exit(-1);
}

TibrvCmQueueTransport rvCmqTransport;
if ((status = rvCmqTransport.create(&rvTransport, RVDQ_SERVICE_POOL))
!= TIBRV_OK) {
printf ("cannot create TibrvCmQueueTransport : %s.\n",
status.getText());
exit(-1);
}

/*
* Instantiate WorldHelloService and have constructor set up the default
* event queue
*/
WorldHelloService worldHelloService (&rvCmqTransport,
(TibrvQueue*)0,
RVDQ_LISTEN_SUBJECT,
gNum);

if(! worldHelloService.isValid())
{

Page 114 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

printf("TAWrvService constructor failed - %s\n",

worldHelloService.getErrorMsg());
exit(-1);
}
printf("listening to %s for requests\n", RVDQ_LISTEN_SUBJECT);
if(! worldHelloService.enableRequests() ) {
printf("Unable to enable request processing - %s\n",
worldHelloService.getErrorMsg());
}
else {
worldHelloService.fence(); // wait forever
}

return 0;
}

TIB/Adapter for Web User’s Guide Page 115

HelloGoodbye Service C++ Example

HelloGoodbye Service C++ Example

This is another service pool example. This shows how an initial request can be directed to
a worker service by the RVDQ scheduler, and how the direct request subject is used to
bypass the RVDQ scheduler for subsequent requests from the same client. In addition to
returning a language-specific greeting like worldhello.cc, this service also returns a
hyperlink that contains the direct request subject. When this hyperlink is clicked, the
client communicates directly with the service instance that provided the greeting page.
This idiom is useful when you need to maintain a session between client and service, as
well as between fault tolerant and load balanced services.

Starting the Program

Start multiple instances of this program from the command line. For example:
> hellogoodbye 0 1000 &
> hellogoodbye 1 1001 &
> hellogoodbye 2 1002 &

This runs three instances in the background. The listen subject, taw.hellogoodbye is
hardcoded into the program.
If /servlet/TAW is the URL mapping in your web browser type:
http://<your web server>/servlet/TAW?subject=taw.hellogoodbye
Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser,
just as you did with worldhello.
Now, if you click “Now say goodbye.”, the URL behind this link causes a request to be
made using the direct request subject. The same service instance that responded with the
greeting will now say goodbye in the same language.

Source Code
The hellogoodbye.cc file where the service pool is defined is given next. In the code, the
basic steps are to:

Derive a subclass from TAWrvService that provides an implementation of the abstract
method onMsg().

The onMsg() method is invoked by TAW whenever a request is received. This
implementation returns a greeting in either Japanese, English, or French according to

Page 116 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

command line arguments. It also computes a direct request subject that is used to
prepare a hyperlink that uses this subject to recontact this service instance.

The onDirectMsg() method is invoked by TAW whenever a request to the direct
request subject is received. It will return Goodbye in the same language that it used to
return Hello.

You must provide a properly initialized TibRvCmqueueTransport to your constructor.

These four parameter definitions determine how RVDQ decides when to promote a
worker to scheduler. See the TIB/Rendezvous documentation for more details on
these parameters.

Create an instance of HelloGoodbyeService that uses a command line argument to
determine which language to use for hello and goodbye.

After instantiating your TAWrvService subclass, you should make sure that it is valid
before proceeding further. The isValid method is used for this purpose.

If the object is not valid, the reason may be determined by invoking the getErrorMsg
method.

Start request processing.

hellogoodbye.cc
#include "rv6/TAWrv.h"

#include "string.h"
#include "stdio.h"
#include "stdlib.h"

#define RVDQ_LISTEN_SUBJECT "taw.hellogoodbye"

#define RVDQ_SERVICE_POOL "hellogoodbye"

const char* hellos[] = { "Hello", "Bon jour", "Konnichiwa", "Namaste",

"Salaam Malakum", 0 };
const char* goodbyes[] = { "Goodbye", "Au revoir", "Sayounara", "Phir
Ana", "Ma Salama", 0 };

#define NUMGREETINGS 5

/* Define an RVDQ-based service */

class HelloGoodbyeService : public TAWrvService
{
public:
HelloGoodbyeService(TibrvCmQueueTransport *pRvCmqTransport, TibrvQueue
*pQueue, const char* requestSubject, int iGreetingNumber, int uniqueId);

TIB/Adapter for Web User’s Guide Page 117

HelloGoodbye Service C++ Example

~HelloGoodbyeService(){};
void onMsg(TAWrvRequest* pRequest);
void onDirectMsg(TAWrvRequest* pRequest);
protected:
int _iGreetingNumber;
};

HelloGoodbyeService::HelloGoodbyeService(TibrvCmQueueTransport
*pRvCmqTransport, TibrvQueue *pQueue, const char* requestSubject, int
iGreetingNumber,int uniqueId)
: TAWrvService(pRvCmqTransport, pQueue, requestSubject)
{
// Determine which greeting to return
_iGreetingNumber = iGreetingNumber % NUMGREETINGS;

// compute a direct request subject based on greeting index

char buf[512];
sprintf(buf, "%s.%d", getRequestSubject(), uniqueId);
setDirectRequestSubject(buf);

// Handle request forwarded by the RVDQ scheduler

void
HelloGoodbyeService::onMsg(TAWrvRequest* pRequest)
{
/* Return a page containing a greeting and a hyperlink to the
goodbye message in the same language */
char buf[512];
char *subj = new char[::strlen(getDirectRequestSubject())+1];
::strcpy(subj, getDirectRequestSubject());

// Return appropriate language greeting and hyperlink containing

// a URL that embeds uses the direct request subject

sprintf(buf, "<html><body><h2>%s. <a href=\"/servlet/TAW?subject=%s\">

Now say goodbye. </a></body></html>", hellos[_iGreetingNumber], subj);
delete [] subj;
pRequest->setHttpReplyHeader("content-type","text/html");
pRequest->reply(buf);
};

// Handle direct request from web server

void
HelloGoodbyeService::onDirectMsg(TAWrvRequest* pRequest)
{
char buf[512];
sprintf(buf, "<html><body><h2>%s</body></html>",
goodbyes[_iGreetingNumber]);
pRequest->setHttpReplyHeader("content-type","text/html");
pRequest->reply(buf);
}

Page 118 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

int main(int argc, char** argv)

{
if( argc < 3 )
{
printf("usage: %s <language index> <unique id>\n", argv[0]);
exit(-1);
}
int gNum = atoi(argv[1]);
int uniqueId = atoi(argv[2]);

char* rvService = getenv("SERVICE");

char* rvNetwork = getenv("NETWORK");
char* rvDaemon = getenv("DAEMON");

TibrvStatus status;

if ((status = Tibrv::open()) != TIBRV_OK) {

printf ("cannot open internal machinery : %s.\n", status.getText());
exit(-1);
}

TibrvNetTransport rvTransport;
if ((status = rvTransport.create(rvService, rvNetwork, rvDaemon)) !=
TIBRV_OK) {
printf ("cannot create TibrvNetTransport : %s.\n", status.getText());
exit(-1);
}

TibrvCmQueueTransport rvCmqTransport;
if ((status = rvCmqTransport.create(&rvTransport, RVDQ_SERVICE_POOL))
!= TIBRV_OK) {
printf ("cannot create TibrvCmQueueTransport : %s.\n",
status.getText());
exit(-1);
}

/*
* Instantiate HelloGoodbyeService and have a constructor set up the
* default event queue
*/
HelloGoodbyeService helloGoodbyeService(&rvCmqTransport,
(TibrvQueue*)0, RVDQ_LISTEN_SUBJECT, gNum, uniqueId);

if(!helloGoodbyeService.isValid())
{
printf("TAWrvService constructor failed - %s\n",
helloGoodbyeService.getErrorMsg());
exit(-1);
}
printf("listening to %s for requests\n", RVDQ_LISTEN_SUBJECT);
if(! helloGoodbyeService.enableRequests() ) {
printf("Unable to enable request processing - %s\n",
helloGoodbyeService.getErrorMsg());

TIB/Adapter for Web User’s Guide Page 119

HelloGoodbye Service C++ Example

}
else {
helloGoodbyeService.fence(); // wait forever
}

return 0;
}

Page 120 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

MultiDispatcher Service C++ Example

The multidispatcher service example illustrates how to create more than one dispatcher
thread to dispatch events from the queue. Typically one dispatcher thread is used to
dispatch events. By creating multiple dispatcher threads, it allows multiple requests to be
processed simultaneously.

Starting the Program

C++ usage: multiDispatcher <listen subject> <number of dispatchers>
To run the example:
1. Start the service instance multipDispatcher. For example:
multiDispatcher taw.dispatch.one 1

multiDispatcher taw.dispatch.three 3

2. Modify task.html in the POST action=http://<server>/servlet/TAW

3. Create multiple browser windows with task.html (for example, three windows)
4. Fill in the subject taw.dispatch.one, job number, processing time. For example:
job number 1001, processing time 10

job number 1002, processing time 7

job number 1003, processing time 2

and submit the forms with jobs all at once (=1001,1002,1003 consecutively).
The sequence of replying from the browser is 1001,1002,1003 with the time displayed.
5. Replace the subject with taw.dispatch.three and submit the forms again.
You will notice the sequence of reply from the browser is in different order, most likely
1003, 1002, 1001 because the processing time for job number 1003 is the least and we have
three threads to handle the tasks.

Source Code
The multiDispatcher.cc file is defined is given next.

TIB/Adapter for Web User’s Guide Page 121

MultiDispatcher Service C++ Example

multiDispatcher.cc
#include "rv6/TAWrv.h"
#include "stdio.h"
#include "time.h"

class MultiDispatcherService : public TAWrvService

{
public:
MultiDispatcherService(TibrvTransport *pRvTransport, TibrvQueue
*pQueue, const char* requestSubject)
: TAWrvService(pRvTransport, pQueue, requestSubject) {};
~MultiDispatcherService() {};
void onMsg(TAWrvRequest* pRequest);

void waitSecs(int secs) {

TibrvQueue _queue; // Emulate wait
_queue.create(); // By creating an empty queue and wait till secs
_queue.timedDispatch(secs); // If no events are placed in this queue
}
};

void
MultiDispatcherService::onMsg(TAWrvRequest* pRequest)
{
char timeStr[50];
time_t responseTime;
const char* jobid;
int processingTime;
char buf[100];

// Get parameters from task.html form

jobid = pRequest->getUrlParameter("jobid") ?
pRequest->getUrlParameter("jobid") : "N/A";

processingTime = pRequest->getUrlParameter("processingTime") ?
atoi(pRequest->getUrlParameter("processingTime")) : -1;

if (processingTime > -1 && strcmp(jobid, "N/A") != 0) {

// Emulate processing of a task, work for processingTime secs
waitSecs(processingTime);
responseTime = time(0); // get current time
strftime(timeStr, 100, "%Y-%B-%d %I:%m:%S",
localtime(&responseTime));
sprintf(buf, "Finish processing job %s [process time=%d] at %s",
jobid, processingTime, timeStr);
}
else {
sprintf(buf, "Job id or processing time is not valid.");
}

pRequest->setHttpReplyHeader("content-type","text/plain");
pRequest->reply(buf);

Page 122 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

int main(int argc, char** argv)

{
if (argc < 3)
{
printf("usage: %s <listen subject> <number of dispatchers>\n",
argv[0]);
exit(-1);
}

char* subject = argv[1];

int numDispatcher = atoi(argv[2]);

TibrvStatus status;

printf ("number of dispatcher threads for a queue: %d\n",

numDispatcher);
printf ("listening to %s for requests\n", subject);

if ( (status = Tibrv::open()) != TIBRV_OK) {

printf ("cannot open internal machinery : %s.\n", status.getText());
exit(-1);
}

TibrvQueue queue;

if ( (status = queue.create()) != TIBRV_OK) {

printf ("cannot operate TibrvQueue: %s\n", status.getText());
exit(-1);
}

//
// Instantiate MultiDispatcherService, pass the event queue created
// to the constructor and has constructor set up a transport object
//
MultiDispatcherService multiDispatcherService((TibrvTransport*)0,
&queue, subject);
if (! multiDispatcherService.isValid())
{
printf("TAWrvService constructor failed - %s\n",
multiDispatcherService.getErrorMsg());
exit(-1);
}

// Get the queue it is using

TibrvQueue *pQueue = multiDispatcherService.getDispatchQueue();

//
// Create more dispatcher threads and associate them to the queue
// TAWrvService internally would create one dispatcher thread
//

TIB/Adapter for Web User’s Guide Page 123

MultiDispatcher Service C++ Example

for (int i=0; i<numDispatcher-1; i++) {

TibrvDispatcher *pDispatcher = new TibrvDispatcher();
if ((status = pDispatcher->create(pQueue)) != TIBRV_OK) {
printf ("cannot operate a dispatcher thread: %s\n",
status.getText());
exit(-1);
}
}

if (! multiDispatcherService.enableRequests() ) {
printf("Unable to enable request processing - %s\n",
multiDispatcherService.getErrorMsg());
}
else {
multiDispatcherService.fence(); // wait forever
}

return 0;
}

Page 124 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

Simple Service Registry C++ Example

The simple service registry example demonstrates the service registry functionality of the
servlet. For example, when you start three programs,

simplesvcReg svc server.1 "response from server 1"

simplesvcReg svc server.2 "response from server 2"

simplesvcReg svc server.3 "response from server 3"

The programs register to the servlet as the service svc and listen on request subjects of
server.1, server.2, and server.3.

When you issue URL=http://<server>/servlet/TAW?service=svc in the browser, the

servlet chooses among the services that belong to the service name svc and selects one of
them based on its mechanism (load-balancing criteria, or application specific criteria) and
returns a message to the browser.

Starting the Program

C++ usage: simplesvcReg <service name> <service subject> <reply string> [<heartbeat subject>
<announce subject>]

heartbeat subject is the heartbeat subject name the service instance is publishing
constantly, telling the servlet that it is up for service,

announce subject is the announce subject name that the servlet announces itself that it is
up, so that service instance will be aware and send a heartbeat in response to the
announce.
If the two subjects are not specified, the default is used.

Source Code
The simplesvcReg.cc file is given next.

simplesvcReg.cc
#include "rv6/TAWrv.h"
#include "rv6/APSvc.h"
#include "stdlib.h"
#include "string.h"

TIB/Adapter for Web User’s Guide Page 125

Simple Service Registry C++ Example

class SimpleServiceReg : public TAWrvService

{
public:
SimpleServiceReg(TibrvTransport *pRvTransport,
TibrvQueue *pQueue,
const char* serviceName,
const char* requestSubject,
const char* replyString,
const char* hbSubj,
const char* annSubj,
double hbInt,
double failInt);
~SimpleServiceReg() {
delete _pServiceRegistry;
}
void onMsg(TAWrvRequest* pRequest);

private:
const char* _replyString;
APSvc* _pServiceRegistry;
};

SimpleServiceReg::SimpleServiceReg(TibrvTransport *pRvTransport,
TibrvQueue *pQueue,
const char* serviceName,
const char* requestSubject,
const char* replyString,
const char* hbSubj,
const char* annSubj,
double hbInt,
double failInt)
: TAWrvService(pRvTransport, pQueue, requestSubject),
_replyString(replyString)
{
const TibrvTransport *pTransport = getTibrvTransport();

/*
* Instantiate APSvc class that implements the heartbeat protocol for TAW
* service registry
*/

_pServiceRegistry = new APSvc(serviceName, requestSubject,

(TibrvTransport*) pTransport, hbSubj, hbInt, failInt, annSubj,
APSVC_ENABLED);

_pServiceRegistry->start(); /* Start sending heartbeats */

};

void
SimpleServiceReg::onMsg(TAWrvRequest* pRequest)

Page 126 TIB/Adapter for Web User’s Guide

 Chapter 5 C++ API for TIB/Rendezvous 6.x

{
pRequest->reply(_replyString);
}

int main(int argc, char** argv)

{
if(argc < 4)
{
printf("usage: %s <service name> <service subject> <reply string>
[<heartbeat subject> <announce subject>]\n", argv[0]);
exit(-1);
}
double hbInt = 5.0; // heartbeat interval in secs, intervals between
// each heartbeat
double failInt = 11.0; // failure interval in secs, period that servlet
// should declare it is out of service

char* serviceName = argv[1]; // service name

char* serviceSubject = argv[2]; // service subject
char* replyString = argv[3]; // reply string
const char* hbSubj = argc > 4 ? argv[4] : "TAW.heartbeat"; // heartbeat
// subject
const char* annSubj = argc > 5 ? argv[4] : "TAW.announce"; // announce
// subject

TibrvStatus status;

printf("service name = %s, heartbeat subject = %s, announce subject =

%s\n", serviceName, hbSubj, annSubj);
printf("listening on: %s\nreplying with: \"%s\"\n",
serviceSubject, replyString);
if ( (status = Tibrv::open()) != TIBRV_OK) {
printf ("cannot open internal machinery : %s.\n", status.getText());
exit(-1);
}

/*
* Instantiate SimpleService and have constructor setup a transport
* object and the default event queue
*/
SimpleServiceReg simpleServiceReg((TibrvTransport*)0,
(TibrvQueue*)0,
serviceName,
serviceSubject,
replyString,
hbSubj, annSubj,
hbInt, failInt);
if(!simpleServiceReg.isValid())
{
printf("TAWrvService constructor failed - %s\n",
simpleServiceReg.getErrorMsg());
exit(-1);
}

TIB/Adapter for Web User’s Guide Page 127

Simple Service Registry C++ Example

/* Start listening for requests */

if(! simpleServiceReg.enableRequests() ) {
printf("Unable to enable request processing - %s\n",
simpleServiceReg.getErrorMsg());
}
else {
simpleServiceReg.fence(); // wait forever...
}

return 0;
}

Page 128 TIB/Adapter for Web User’s Guide

Chapter 6 Java API Reference for
TIB/Rendezvous 6.x

This chapter describes the Java API for TIB/Rendezvous 6.x. Use this API to write
TIB/Adapter for Web service instances when linking to TIB/Rendezvous 6.x. With this
API you can also create a service pool and use TIB/Rendezvous version 6.x distributed
queues or the TAW service registry to load balance requests to service pool members.

Topics

Overview, page 130

com.tibco.portal.gw.web.api.rv6.TAWrvService, page 132

com.tibco.portal.gw.web.api.rv6.TAWrvRequest, page 147

com.tibco.portal.gw.web.api.rv6.TAWrvException, page 157

com.tibco.portal.svcreg.APSvc, page 158

com.tibco.portal.svcreg.APSvcImpl, page 165

Compiling the Service Examples, page 179

Simple Service Java Example, page 180

File Service Java Example, page 182

WorldHello Java Example, page 185

HelloGoodbye Java Example, page 187

MultiDispatcher Service Java Example, page 190

Simple Service Registry Java Example, page 193

Raw Service Java Example, page 196

TIB/Adapter for Web User’s Guide Page 129

Overview

Overview

Your TIB/Adapter for Web service instances must perform the following basic steps:
1. Make sure that taweb.jar and tibrvj.jar are in your CLASSPATH. If your
applications use the service registry, svcreg.jar must also be in your CLASSPATH.
2. Create a subclass of TAWrvService that implements TAWrvService::onMsg(). Inside
onMsg(), arrange for one of the TAWrvRequest::reply() methods to return data to
the servlet.
3. In your subclass main program, instantiate your TAWrvService subclass, and then call
its enableRequests() method to begin listening for requests.
The example programs, SimpleSvc and FileSvc illustrate this basic structure. They also
show how to handle non-text data and manipulate HTTP reply headers.

Service Pools
In some applications, the request rate can exceed the capacity of a single service instance.
A service pool is a fault-tolerant and load-balanced collection of services.
TIB/Rendezvous Distributed Queues (RVDQ) ensure that a request is delivered to only
one pool member. The service registry API can also be used for load balancing. See
Building Service Instances on page 4 for an overview of both methods.
The TAW Java API makes it very convenient to set up service pools. For more information
on setting up service pools, see RVDQ Service Pools on page 316.

Classes
There are three classes that you need to know to use the Java API.

com.tibco.portal.gw.web.api.rv6.TAWrvService

com.tibco.portal.gw.web.api.rv6.TAWrvRequest

com.tibco.portal.gw.web.api.rv6.TAWrvException
The interface for these classes are described in this chapter.
Use the following interface and class to call the service registry API:

com.tibco.portal.svcreg.APSvc

Page 130 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

com.tibco.portal.svcreg.APSvcImpl

Java Example Service Instances for TIB/Rendezvous 6.x

Seven example Java programs are provided with TIB/Adapter for Web. The sample
source programs illustrate how to write both simple service instances as well as more
complex RVDQ-based services.

SimpleSvc. This is a glorified "Hello World!" program that allows you to specify the
subject the service will listen for requests on, and the string it will return. See Simple
Service C++ Example on page 105 for details.

FileSvc. This shows how to transmit string or binary data and set HTTP reply
headers. See File Service C++ Example on page 108 for details.

WorldHello. This is a service pool example. Depending on the command line
argument given, the service will return a language-specific greeting. See WorldHello
Java Example on page 185 for details.

HelloGoodbye. This is another service pool example. This shows how an initial
request can be directed to a worker service by the RVDQ scheduler, and how the
direct request subject is used to bypass the RVDQ scheduler for subsequent requests
from the same client. See HelloGoodbye Java Example on page 187 for details.

MultiDispatcher. This example illustrates how to create more than one dispatcher
thread to dispatch events from the queue. Typically one dispatcher thread is used to
dispatch events. By creating multiple dispatcher threads, it allows multiple requests
to be processed simultaneously. See MultiDispatcher Service Java Example on page
190 for details.

SimplesvcReg. This example demonstrates the service registry functionality of the
servlet. See Simple Service Registry Java Example on page 193 for details.

RawSvc. This example demonstrates using TIB/Rendezvous directly instead of using
the TAW API. See Raw Service Java Example on page 196 for details.

TIB/Adapter for Web User’s Guide Page 131

com.tibco.portal.gw.web.api.rv6.TAWrvService

com.tibco.portal.gw.web.api.rv6.TAWrvService
RV 6.x only
Class

java.lang.Object

com.tibco.portal.gw.web.api.rv6.TAWrvService

Declaration
public abstract class TAWrvService extends java.lang.Object
implements com.tibco.tibrv.TibrvMsgCallback

Purpose
TAWrvService is an abstract base class that all TAW service instances must subclass. Your
subclass must implement the onMsg() method that is invoked whenever a request is
received from TIB/Rendezvous. The onMsg() method will receive TAWrvRequest objects
that contain all of the HTTP information about the request as well as any data.

Member Summary

Name Description Page

TAWrvService() Constructors 134

TAWrvService.get...() Accessors Accessor methods 139

TAWrvService.onMsg() Invoked in response to requests 140

received on the standard request
subject.

TAWrvService.onDirectMsg() Invoked in response to requests 141

received on the direct request
subject.

TAWrvService.setRequestSubject() Determine the subject the service 142

will use to listen for reliable
requests or RVDQ-based requests

Page 132 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

Name Description Page

TAWrvService.setDirectRequestSub Determine the subject the service 143

ject()
will use to listen for requests that
are not subject to RVDQ
load-balancing

TAWrvService.enableRequests() Start listening for requests 144

TAWrvService.disableRequests() Stop listening requests 145

TAWrvService.isEnabled() Return true if requests are enabled 146

Inherited Methods
The following methods are inherited from java.lang.Object:
clone
equals
finalize
getClass
hashCode
notify
notifyAll
toString
wait

TIB/Adapter for Web User’s Guide Page 133

com.tibco.portal.gw.web.api.rv6.TAWrvService

TAWrvService()
RV 6.x only
Constructor

Declarations
public TAWrvService() throws com.tibco.tibrv.TibrvException

public TAWrvService(com.tibco.tibrv.TibrvTransport transport) throws

com.tibco.tibrv.TibrvException

public TAWrvService(com.tibco.tibrv.TibrvTransport transport,

com.tibco.tibrv.TibrvQueue queue) throws com.tibco.tibrv.TibrvException

public TAWrvService(com.tibco.tibrv.TibrvTransport transport,

com.tibco.tibrv.TibrvQueue queue, java.lang.String requestSubject) throws
com.tibco.tibrv.TibrvException, com.tibco.portal.gw.web.TAWException

public TAWrvService(com.tibco.tibrv.TibrvTransport transport,

com.tibco.tibrv.TibrvQueue queue, java.lang.String requestSubject,
java.lang.String directRequestSubject) throws
com.tibco.portal.gw.web.TAWException, com.tibco.tibrv.TibrvException

public TAWrvService(com.tibco.tibrv.TibrvCmQueueTransport
cmqQueueTransport) throws com.tibco.tibrv.TibrvException

public TAWrvService(com.tibco.tibrv.TibrvCmTibrvTransport
cmqQueueTransport, TibrvQueue queue) throws
com.tibco.tibrv.TibrvException

public TAWrvService(com.tibco.tibrv.TibrvCmQueueTransport
cmqQueueTransport, TibrvQueue queue, java.lang.String requestSubject)
throws com.tibco.tibrv.TibrvException,
com.tibco.portal.gw.web.TAWException

public TAWrvService(com.tibco.tibrv.TibrvCmQueueTransport
cmqQueueTransport, TibrvQueue queue, java.lang.String requestSubject,
java.lang.String directRequestSubject) throws
com.tibco.tibrv.TibrvException, com.tibco.portal.gw.web.TAWException

Purpose
Constructors for the TAWrvService class.

Name Description

TAWrvService() Create a new service instance..

Throws a TibrvException if Tibrv or TibrvTransport
creation fails.

Page 134 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

Name Description

TAWrvService(transport) Create a new service instance using an existing

reliable TIB/Rendezvous transport.
transport—TibrvTransport. Existing transport to
embed in the service instance or null to create a transport.
Throws a TibrvException if Tibrv or TibrvTransport
creation fails.

TAWrvService(transport, Create a new service instance using an existing

queue)
reliable TIB/Rendezvous transport.
transport—TibrvTransport. Existing transport to
embed in the service instance or null to create a transport.
queue—TibrvQueue to pass in a queue or null to
use the default queue
Throws a TibrvException if Tibrv or TibrvTransport
creation fails.

TAWrvService(transport, Create a new service instance using an existing

queue, requestSubject)
reliable TIB/Rendezvous transport.
transport—TibrvTransport. Existing transport to
embed in the service instance or null to create a transport.
queue—TibrvQueue to pass in a queue or null to
use the default queue
requestSubject—String. Subject name that the
application will be listening for requests on. All
RVDQ-based service pool members listen to this subject,
but RVDQ guarantees delivery to only one member.
Throws a TAWException if the requestSubject is
null or a com.tibco.tibrv.TibrvException if the
TIB/Rendezvous transport or TIB/Rendezvous
creation fails.

TIB/Adapter for Web User’s Guide Page 135

com.tibco.portal.gw.web.api.rv6.TAWrvService

Name Description

TAWrvService(transport, Create a new service instance using an existing

queue, requestSubject,
RVDQ TibrvTransport.
directRequestSubject)
transport—TibrvTransport. Existing transport to
embed in the service instance
queue—TibrvQueue to pass in a queue or null to
use the default queue
requestSubject—String. Subject name that the
application will be listening for requests on. All
RVDQ-based service pool members listen to this subject,
but RVDQ guarantees delivery to only one member.
directRequestSubject—String. For RVDQ-based
applications, this is a secondary subject name used to
provide direct access to a service pool member.
Throws a TTAWException if the requestSubject is
null.

TAWrvService(cmqQueueTran Create a new service instance using an existing

sport)
TIB/Rendezvous reliable transport.
transport—TibrvCmQueueTransport. Existing
TibrvCmQueueTransport to embed in the service
instance.
Throws a com.tibco.tibrv.TibrvException if the
TIB/Rendezvous creation fails.

TAWrvService(cmqQueueTran Create a new service instance using an existing

sport, queue)
reliable TIB/Rendezvous transport.
transport—existing TibrvCmQueueTransport to
embed in the service instance
queue—TibrvQueue to pass in a queue or null to
use the default queue
Throws a TibrvException if Tibrv creation fails.

Page 136 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

Name Description

TAWrvService(cmqQueueTran Create a new service instance with a subject to listen

sport, queue,
on.
requestSubject)
cmtransport—TibrvCmQueueTransport. Existing
TibrvCmQueueTransport to embed in the service
instance
queue—TibrvQueue to pass in a queue or null to
use the default queue
requestSubject—String. Subject name that the
application will be listening for requests on. All
RVDQ-based service pool members listen to this subject,
but RVDQ guarantees delivery to only one member.
Throws a TAWException if the requestSubject is
null or a com.tibco.tibrv.TibrvException if the
TIB/Rendezvous creation fails.

TAWrvService(cmqQueueTran Create a new service instance using an existing

sport, queue,
TIB/Rendezvous certified messaging transport.
requestSubject,
directRequestSubject) cmtransport—TibrvCmQueueTransport. Existing
TibrvCmQueueTransport to embed in the service
instance
queue—TibrvQueue to pass in a queue or null to
use the default queue
requestSubject—String. Subject name that the
application will be listening for requests on. All
RVDQ-based service pool members listen to this subject,
but RVDQ guarantees delivery to only one member.
directRequestSubject—String. For RVDQ-based
applications, this is a secondary subject name used to
provide direct access to a service pool member.
Throws a TAWException if the requestSubject is
null or a com.tibco.tibrv.TibrvException if the
TIB/Rendezvous creation fails.

Remarks
All applications must provide a subclass of TAWrvService that implements the onMsg
method.
Subjects need not be specified here, but must be set prior to enabling the service.

TIB/Adapter for Web User’s Guide Page 137

com.tibco.portal.gw.web.api.rv6.TAWrvService

Example
public class SimpleSvc extends TAWrvService
{
public static void main(String argv[])
{
try
{ ...
{
Tibrv.open(Tibrv.IMPL_NATIVE);
SimpleSvc svc = new SimpleSvc();

[truncated...]

Errors
An error will throw an exception:
try { ...
} catch(Exception ...)

Page 138 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvService.get...() Accessors
RV 6.x only
Methods

Declaration
public java.lang.String getDirectRequestSubject()
public java.lang.String getDispatchQueue()
public java.lang.String getRequestSubject()
public com.tibco.tibrv.TibrvCmQueueTransport getTibrvCmQueueTransport()
public com.tibco.tibrv.TibrvTransport getTibrvTransport()

Purpose
Accessor methods for TAWrvServices instances.

Name Description

getDirectRequestSubject() Returns the secondary subject used by RVDQ-based

services to listen for requests that bypass RVDQ
load-balancing or null.

getDispatchQueue() Returns the event queue to use. This allows association of

the queue with more than one dispatcher thread.

getRequestSubject() Returns the subject used for reliable or RVDQ-based

requests. This subject is used by both RVDQ-based pooled
services, or by singleton applications.

getTibrvCmQueueTransport() Returns the TIB/Rendezvous distributed queueing

transport in use.

getTibrvTransport() Returns the TIB/Rendezvous reliable transport in use.

TIB/Adapter for Web User’s Guide Page 139

com.tibco.portal.gw.web.api.rv6.TAWrvService

TAWrvService.onMsg()
RV 6.x only
Method

Declaration
public abstract void onMsg(TAWrvRequest request)

Purpose
All applications must provide a subclass of TAWrvService that implements the onMsg()
method. The method is called when a request is received from TIB/Rendezvous on the
primary request subject.

Parameters

Name Description

request TAWrvRequest object that encapsulates all data, HTTP

headers and return address information associated with the
request.

Page 140 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvService.onDirectMsg()
RV 6.x only
Method

Declaration
public void onDirectMsg(TAWrvRequest request);

Purpose
This method is only relevant to RVDQ-based service instances. This method is called
when a request is received on the direct request subject. Requests to direct request
subjects are not intercepted by the RVDQ scheduler. The default implementation merely
invokes the onMsg() method.

Parameters

Name Description

request Pointer to the TAWrvRequest object that encapsulates all data,

HTTP header and return address information associated with
the request.

TIB/Adapter for Web User’s Guide Page 141

com.tibco.portal.gw.web.api.rv6.TAWrvService

TAWrvService.setRequestSubject()
RV 6.x only
Method

Declaration
public void setRequestSubject(java.lang.String subject)
throws TAWException

Purpose
Determines which subject the service will listen, either for normal, reliable requests, or for
RVDQ-based requests.

Parameters

Name Description

subject TIB/Rendezvous subject name that the service will use to

listen for requests.

Remarks
An exception is thrown when the request subject is null.

Page 142 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvService.setDirectRequestSubject()
RV 6.x only
Method

Declaration
public void setDirectRequestSubject(java.lang.String subject);

Purpose
Determines which subject the service will use to listen for requests that are not subject to
RVDQ load-balancing. The method only applies RVDQ-based services.

Parameters

Name Description

subject TIB/Rendezvous subject name that the service will use to

listen for direct requests.

TIB/Adapter for Web User’s Guide Page 143

com.tibco.portal.gw.web.api.rv6.TAWrvService

TAWrvService.enableRequests()
RV 6.x only
Method

Declaration
public void enableRequests() throws TAWException

Purpose
Before the service will start receiving requests through its onMsg() method, the
enableRequests() method must be invoked. This sets up the necessary TIB/Rendezvous
listeners.

Parameters
None.

Remarks
Prior to invoking enableRequest(), you must have set the subjects that your service will
accept requests on. You can do this in the constructor, or use setRequestSubject() and
setDirectRequestSubject(). This method creates TibrvListener objects that remain
valid until the disableRequests() method is invoked.
An exception is thrown if no requestSubject has been set, or if a TIB/Rendezvous listener
cannot be created.

Page 144 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvService.disableRequests()
RV 6.x only
Method

Declaration
public void disableRequests();

Purpose
This method allows the service to suspend request processing. This method causes the
service to stop listening for requests.

Remarks
This method destroys the TibrvListener objects created in enableRequests().

Parameters
None.

TIB/Adapter for Web User’s Guide Page 145

com.tibco.portal.gw.web.api.rv6.TAWrvService

TAWrvService.isEnabled()
RV 6.x only
Method

Declaration
public boolean isEnabled();

Purpose
Determines whether the service is currently listening for requests.

Remarks
Returns TRUE if the service is currently listening for requests or FALSE if it is not.

Page 146 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

com.tibco.portal.gw.web.api.rv6.TAWrvRequest
RV 6.x only
Class

java.lang.Object

com.tibco.portal.gw.web.api.rv6.TAWrvRequest

Declaration
public class TAWrvRequest extends java.lang.Object

Purpose
TAWrvRequest objects are manufactured by the TIB/Adapter for Web API when requests
are received. This class encapsulates an HTTP request from the time it is delivered to your
service instance, to after your reply has been transmitted. Its interface consists primarily
of accessors for HTTP protocol information, including the data payload. The reply
method is used to send data back to the browser or other HTTP client.
These objects are created and destroyed by TAW, and are made available to you through
the TAWrvService member callback functions onMsg() and onDirectMsg().

Member Summary

Name Description Page

TAWrvRequest() Constructor 149

TAWrvRequest.get...() Methods to get a value for TAWrvRequest 150

Accessors
instances

TAWrvRequest.reply...() Methods to send a reply for 153

TAWrvRequest instances

TAWrvRequest.set...() Methods to set a value for TAWrvRequest 155

instances

Inherited Methods
The following methods are inherited from java.lang.Object:
clone
equals
finalize

TIB/Adapter for Web User’s Guide Page 147

com.tibco.portal.gw.web.api.rv6.TAWrvRequest

getClass
hashCode
notify
notifyAll
toString
wait

Page 148 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvRequest()
RV 6.x only
Constructor

Declarations
public TAWrvRequest(com.tibco.tibrv.TibrvMsg msg,
com.tibco.tibrv.TibrvTransport transport)

Purpose
Sets up an object that is used to respond to a request.
Although a constructor is provided, it typically is not used because the object is created
internally during the callback.

Parameters

Name Description

msg Incoming TibrvMsg (from a listener callback).

transport Transport to use in the reply.

TIB/Adapter for Web User’s Guide Page 149

com.tibco.portal.gw.web.api.rv6.TAWrvRequest

TAWrvRequest.get...() Accessors
RV 6.x only
Methods

Declaration
// ----------------- Request ------------------
public java.lang.String getHttpHeader(java.lang.String name) throws
TAWException
public com.tibco.tibrv.TibrvMsg getHttpHeaders() throws TAWException
public java.lang.String getHttpMethod() throws TAWException
public java.lang.String getHttpUri() throws TAWException
public java.lang.String getHttpVersion() throws TAWException
public int getProtocolVersion()
public java.lang.String getUrlParameter(java.lang.String name)
public com.tibco.tibrv.TibrvMsg getUrlParameters() throws TAWException
public java.lang.String getUrlPath() throws TAWException
public java.lang.String getUrlResource() throws TAWException
public int getProtocolVersion() throws TAWException

// ----------------- Reply------------------
public java.lang.Object getHttpReplyEntityBody() throws TAWException
public java.lang.Object getHttpReplyHeader(java.lang.String name)
public com.tibco.tibrv.TibrvMsg getHttpReplyHeaders() throws TAWException
public java.lang.String getHttpReplyReasonPhrase()
public int getHttpReplyStatusCode()
public TibrvMsg getReplyMsg() throws TAWException
public java.lang.String getReplyProtocolVersion()

Purpose
The next table lists the request accessors for TAWrvRequest instances.

Request Accessors Description

getHttpHeader(name) Returns an individual request header value by name, given

the header name. The lookup is case insensitive.
If multiple values are associated with the headers of the
same name, only one value will return. Use
getHttpHeaders() to manually get all the values.
Parameter:
name—String. Name of header or null if not found.
An exception is thrown if the HTTP header field is not
found.

Page 150 TIB/Adapter for Web User’s Guide


Request Accessors
getHttpHeaders()
getHttpMethod()
getHttpUri()
getHttpVersion()
getProtocolVersion()
getUrlParameter(name)
getUrlParameters()
getUrlPath()
TIB/Adapter for Web User’s Guide
Chapter 6 Java API Reference for TIB/Rendezvous 6.x
Description
Returns all of the HTTP request headers. It returns a
TibrvMsg containing one field for each header.
An exception is thrown if the HTTP header fields are not
found.
Returns the HTTP method from the HTTP request line.
An exception is thrown if the HTTP method field is not
found.
Returns the HTTP URI from the HTTP request line.
An exception is thrown if the HTTP Uri is not found.
Returns the HTTP version from the HTTP request line.
An exception is thrown if the HTTP version field is not
found.
Returns the TAW version number. An exception is thrown if
the HTTP TAW version field is not found.
Returns the value of a given individual query parameter
from the URL on the request line by name. The lookup is
case sensitive.
Parameter:
name—String. Query parameter from the URL.
An exception is thrown if the URL parameter field is not
found.
Returns all query parameters from the URL on the request
line. It returns a TibrvMsg containing one field for each
parameter.
An exception is thrown if the URL parameter fields are not
found.
Returns the path from the HTTP request line. An exception
is thrown if the value of the corresponding TibrvMsg field is
not a string.
An exception is thrown if the URL path field is not found.
Page 151
com.tibco.portal.gw.web.api.rv6.TAWrvRequest
Request Accessors
getUrlResource()
The next table lists the reply accessors for TAWrvRequest instances.
Rely Accessors
getHttpReplyEntityBody()
getHttpReplyHeader(name)
getHttpReplyHeaders()
getHttpReplyReasonPhrase()
getHttpReplyStatusCode()
getReplyMsg()
getReplyProtocolVersion()
Page 152
Description
Returns the resource from the HTTP request line.
An exception is thrown if the URL resource field is not
found.
Description
Returns the reply entity body object that needs to be cast to
the appropriate type (String or byte[]).
An exception is thrown if the entity body is null.
Returns the object for a given Http Header, given the name
of field to get. The lookup is case insensitive.
If multiple values are associated with the headers of the
same name, only one value will return. Use
getHttpReplyHeaders() to manually get all the values.
name—String. Name of field to get.
Returns the current set of Http Headers. It returns a
TibrvMsg containing one field for each header
An exception is thrown if there is an error in creating
TibrvMsg.
Returns the status phrase that was set.
Returns the status code that was set.
Returns the TibrvMsg reply after the reply() function is
called. Use this method for debugging to verify the message
is constructed as desired.
An exception is thrown if there is an error in creating
TibrvMsg.
Returns the TAW version number.
TIB/Adapter for Web User’s Guide
 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvRequest.reply...()
RV 6.x only
Methods

Declaration
public void reply() throws TAWException
public void reply(byte[] entityBody) throws TAWException
public void reply(byte[] entityBody, int statusCode) throws TAWException
public void reply(byte[] entityBody, int statusCode, java.lang.String
reasonPhrase) throws TAWException
public void reply(java.lang.String entityBody) throws TAWException
public void reply(java.lang.String entityBody, int statusCode) throws
TAWException
public void reply(java.lang.String entityBody, int statusCode,
java.lang.String reasonPhrase) throws TAWException

Purpose
Send a reply back to the HTTP client. The next table lists and explains the reply() methods.

Name Description

reply() Sends a reply back to the HTTP client through the web
browser when all HTTP reply information, including reply
data has been set via TAWrvRequest accessor methods.
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

reply(entityBody) Sends a reply containing binary data back to the HTTP

client through the web browser. The default HTTP reply
status code (200) and reason phrase ("OK") are used.
entityBody—byte[]. Binary data
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

reply(entityBody, statusCode)
Sends a reply containing binary data back to the HTTP
client through the web browser. The default HTTP reason
phrase ("OK") is used.
entityBody—byte[]. Binary data
statusCode—Int. HTTP reply status code
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

TIB/Adapter for Web User’s Guide Page 153

com.tibco.portal.gw.web.api.rv6.TAWrvRequest

Name Description

reply(entityBody, statusCode,
reasonPhrase)
This method is used to send a reply containing binary data
back to the HTTP client through the web browser.
entityBody—byte[]. Binary data
statusCode—Int. HTTP reply status code
reasonPhrase—String. HTTP reply reason phrase
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

reply(entityBody) Sends a reply containing string data back to the HTTP client
through the web browser. The default HTTP reply status
code (200) and reason phrase ("OK") are used.
entityBody—String. String data
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

reply(entityBody, statusCode)
Sends a reply containing string data back to the HTTP client
through the web browser. The default HTTP reason phrase
("OK") is used.
entityBody—String. String data
statusCode—Int. HTTP reply status code
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

reply( entityBody, statusCode,
reasonPhrase)
Sends a reply containing string data back to the HTTP client
through the web browser.
entityBody—String. String data
statusCode—Int. HTTP reply status code
reasonPhrase—String. HTTP reply reason phrase
An exception is thrown if a TIB/Rendezvous error occurs
during the reply transmission.

Page 154 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

TAWrvRequest.set...()
RV 6.x only
Methods

Declaration
public void setHttpReplyEntityBody(byte[] body)
public void setHttpReplyEntityBody(java.lang.String body)
public void setHttpReplyHeader(java.lang.String name, int value)
public void setHttpReplyHeader(java.lang.String name, java.lang.String
value)
public void setHttpReplyReasonPhrase(java.lang.String phrase)
public void setHttpReplyStatus(int code, java.lang.String phrase)
public void setHttpReplyStatusCode(int code)

Purpose
Sets a value for TAWrvRequest instances.

Name Description

setHttpReplyEntityBody(body)
Sets binary data into the HTTP entity body (i.e. data
payload) of the reply.
body—byte[]. Binary payload data
—or—
body—String. Payload data.

setHttpReplyHeader(name value)
Sets the value of a named HTTP header to a value. Any
preexisting value for that header is appended.
name—String. Header name
value—Int. Value of header
—or—
value—String. Value of header

setHttpReplyReasonPhrase( Sets the reply HTTP reason phrase that should

phrase) accompany the status code.
phrase—String. HTTP reason phrase

setHttpReplyStatus(code, phrase) Sets the reply HTTP reason phrase and status code.
code—Int. HTTP status code
phrase—String. HTTP reason phrase

TIB/Adapter for Web User’s Guide Page 155

com.tibco.portal.gw.web.api.rv6.TAWrvRequest

Name Description

setHttpReplyStatusCode(code) Sets the reply status code.

code—Int. HTTP reply status code

Page 156 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

com.tibco.portal.gw.web.api.rv6.TAWrvException
RV 6.x only
Class

java.lang.Object

java.lang.Throwable

java.lang.Exception

com.tibco.portal.gw.web.api.rv6.TAWException

Declaration
public class TAWException extends java.lang.Exception

Purpose
The TAWrvException class is used to report TAW errors.

Inherited Methods
The following methods are inherited from java.lang.Object:
clone
equals
finalize
getClass
hashCode
notify
notifyAll
toString
wait
The following methods are inherited from java.lang.Throwable:
fillInStackTrace
getLocalizedMessage
getMessage
printStackTrace
toString

TIB/Adapter for Web User’s Guide Page 157

com.tibco.portal.svcreg.APSvc

com.tibco.portal.svcreg.APSvc
RV 6.x only
Interface

java.lang.Runnable

com.tibco.portal.svcreg.APSvc

Declaration
public interface APSvc
extends java.lang.Runnable

Purpose
This interface is used by a service instance to register itself with all clients that have
embedded an APSvcRegistry instance. It handles the heartbeat protocol.

Member Summary

Name Description Page

APSvc.appendToHeartbeat() Called just before a heartbeat is 159

emitted.

APSvc.disable() Inform all service instances this 160

service instance is unable to receive
requests.

APSvc.enable() Inform all service instance this 161

service is ready to receive requests.

APSvc.init() Initialize the service instance. 162

APSvc.run() Must be called in the executing 163

thread.

APSvc.terminate() Notify all APSvcRegistry instances 164

that this service instance has exited.

Page 158 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvc.appendToHeartbeat()
RV 6.x only
Method

Declaration
public com.tibco.tibrv.TibrvMsg appendToHeartbeat()

Purpose
The method is called just before a heartbeat is emitted. An implementation is mandatory.
The method returns a TibrvMsg containing auxiliary information to be associated with this service
instance in the client's APSvcRegistry, or null.

TIB/Adapter for Web User’s Guide Page 159

com.tibco.portal.svcreg.APSvc

APSvc.disable()
RV 6.x only
Method

Declaration
public void disable()
throws com.tibco.tibrv.TibrvException

Purpose
Inform all APSvcRegistry instances that this service instance is temporarily disabled and
unable to receive requests.

Page 160 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvc.enable()
RV 6.x only
Method

Declaration
public void enable()
throws com.tibco.tibrv.svcreg.TibrvException

Purpose
Informs all APSvcRegistry instances that this service instance is ready to receive
requests.

TIB/Adapter for Web User’s Guide Page 161

com.tibco.portal.svcreg.APSvc

APSvc.init()
RV 6.x only
Method

Declaration
public void init(java.lang.String serviceName,
java.lang.String requestSubject,
com.tibco.tibrv.TibrvTransport heartbeatTransport,
java.lang.String heartbeatSubject,
double heartbeatInterval,
double failureTolerance,
java.lang.String registrySubject,
byte readyStatus)
throws com.tibco.portal.svcreg.APSvcException,
com.tibco.tibrv.TibrvException

Purpose
Initialize a service registry instance .

Parameters

Name Description

serviceName Service name.

requestSubject A globally unique subject (inbox) for the service instance.

heartbeatTransport TIB/Rendevous transport to be used by the heartbeat protocol.

heartbeatSubject Subject on which heartbeats are published.

heartbeatInterval The number of seconds between heartbeats.

failureTolerance The number of seconds to wait for a heartbeat before marking

this service instance as terminated.

registrySubject Subject on which APSvcRegistry announcements are sent.

readyStatus One of: enabled, disabled, or terminated

Page 162 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvc.run()
RV 6.x only
Method

Declaration
public void run()

Purpose
This method must be implemented by its subclass. When an object implementing
Runnable is used to create a thread, starting the thread causes the object’s run method to
be called in that separately executing thread.

TIB/Adapter for Web User’s Guide Page 163

com.tibco.portal.svcreg.APSvc

APSvc.terminate()
RV 6.x only
Method

Declaration
public void terminate()
throws com.tibco.tibrv.TibrvException

Purpose
Inform all APSvcRegistry instances that this service instance has exited.

Page 164 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

com.tibco.portal.svcreg.APSvcImpl
RV 6.x only
Class

java.lang.Object

com.tibco.portal.svcreg.APSvcImpl

Declaration
public class APSvcImpl
implements com.tibco.portal.svcreg.APSvc
com.tibco.tibrv.TibrvTimerCallback
com.tibco.tibrv.TibrvMsgCallback

Purpose
The APSvcImpl class implements the APSvc heartbeat protocol interface.

Member Summary

Name Description Page

APSvcImpl.APSvcImpl() Constructor 167

APSvcImpl.appendToHeartbeat() Called just before a heartbeat is 168

emitted.

APSvcImpl.disable() Inform all service instances this 169

service instance is unable to receive
requests.

APSvcImpl.enable() Inform all service instance this 170

service is ready to receive requests.

APSvcImpl.init() Initialize the service instance. 171

APSvcImpl.onMsg() Process inbound messages. 173

APSvcImpl.onTimer() Process timer events. 174

TIB/Adapter for Web User’s Guide Page 165

com.tibco.portal.svcreg.APSvcImpl

Name Description Page

APSvcImpl.run() Starts sending heartbeats on the 175

network.

APSvcImpl.sendHeartbeat() Respond to an announcement 176

request by sending a heartbeat.

APSvcImpl.startHeartbeating() Starts sending periodic heartbeats by 177

activating a timer.

APSvcImpl.terminate() Notify all APSvcRegistry instances 178

that this service instance has exited.

Page 166 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvcImpl.APSvcImpl()
RV 6.x only
Constructor

Declaration
public APSvcImpl(java.lang.String serviceName,
java.lang.String requestSubject,
com.tibco.tibrv.TibrvTransport heartbeatTransport,
java.lang.String heartbeatSubject,
double heartbeatInterval,
double failureTolerance,
java.lang.String registrySubject,
byte readyStatus)
throws com.tibco.portal.svcreg.APSvcException,
com.tibco.tibrv.TibrvException

Purpose
Create a service registry instance.

Parameters

Name Description

serviceName Service name.

requestSubject A globally unique subject (inbox) for the service instance.

heartbeatTransport TIB/Rendevous transport to be used by the heartbeat protocol.

heartbeatSubject Subject on which heartbeats are published.

heartbeatInterval The number of seconds between heartbeats.

failureTolerance The number of seconds to wait for a heartbeat before marking

this service instance as terminated.

registrySubject Subject on which APSvcRegistry announcements are sent.

readyStatus One of:

com.tibco.portal.svcreg.APSvcConstants.enabled
com.tibco.portal.svcreg.APSvcConstants.disabled
com.tibco.portal.svcreg.APSvcConstants.terminated

TIB/Adapter for Web User’s Guide Page 167

com.tibco.portal.svcreg.APSvcImpl

APSvcImpl.appendToHeartbeat()
RV 6.x only
Method

Declaration
public com.tibco.tibrv.TibrvMsg appendToHeartbeat()

Purpose
The method is called just before a heartbeat is emitted. The method allows you to append any
auxiliary information to be associated with this service instance in the client's APSvcRegistry by
overriding this method.
The method returns a TibrvMsg containing auxiliary information. The current implementation
returns null.

Page 168 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvcImpl.disable()
RV 6.x only
Method

Declaration
public void disable()
throws com.tibco.tibrv.TibrvException

Purpose
Inform all APSvcRegistry instances that this service instance is temporarily disabled and
unable to receive requests.

TIB/Adapter for Web User’s Guide Page 169

com.tibco.portal.svcreg.APSvcImpl

APSvcImpl.enable()
RV 6.x only
Method

Declaration
public void enable()
throws com.tibco.tibrv.TibrvException

Purpose
Informs all APSvcRegistry instances that this service instance is ready to receive
requests.

Page 170 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvcImpl.init()
RV 6.x only
Method

Declaration
public void init(java.lang.String serviceName,
java.lang.String requestSubject,
com.tibco.tibrv.TibrvTransport heartbeatTransport,
java.lang.String heartbeatSubject,
double heartbeatInterval,
double failureTolerance,
java.lang.String registrySubject,
byte readyStatus)
throws com.tibco.portal.svcreg.APSvcException,
com.tibco.tibrv.TibrvException

Purpose
Initialize a service registry instance . This method is implemented for interface
com.tibco.portal.svcreg.APSvc. It is called by the
com.tibco.portal.svcreg.APSvcImpl constructor. Typically users should not call this
method.
Parameters

Name Description

serviceName Service name.

requestSubject A globally unique subject (inbox) for the service instance.

heartbeatTransport TIB/Rendevous transport to be used by the heartbeat protocol.

heartbeatSubject Subject on which heartbeats are published.

heartbeatInterval The number of seconds between heartbeats.

failureTolerance The number of seconds to wait for a heartbeat before marking

this service instance as terminated.

registrySubject Subject on which APSvcRegistry announcements are sent.

TIB/Adapter for Web User’s Guide Page 171

com.tibco.portal.svcreg.APSvcImpl

Name Description

readyStatus One of:

com.tibco.portal.svcreg.APSvcConstants.enabled
com.tibco.portal.svcreg.APSvcConstants.disabled
com.tibco.portal.svcreg.APSvcConstants.terminated

Page 172 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvcImpl.onMsg()
RV 6.x only
Method

Declaration
public void onMsg(com.tibco.tibrv.TibrvListener listener,
com.tibco.tibrv.svcreg.TibrvMsg msg)

Purpose
Respond to an announcement message from an APSvcRegistry by sending a heartbeat.
This method is implemented for interface com.tibco.tibrv.TibrvMsgCallback. It will
be called when there is an incoming message with the request subject. You need not call
this method.
Parameters

Name Description

listener This parameter receives the listener event.

msg This parameter receives the inbound message.

TIB/Adapter for Web User’s Guide Page 173

com.tibco.portal.svcreg.APSvcImpl

APSvcImpl.onTimer()
RV 6.x only
Method

Declaration
public void onTimer(com.tibco.tibrv.TibrvTimer timer)

Purpose
Process timer events.
This method is implemented for interface com.tibco.tibrv.TibrvTimerCallback. It
will be called when there is a timer event. You need not call this method.
Parameter

Name Description

timer This parameter receives the timer event.

Page 174 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvcImpl.run()
RV 6.x only
Method

Declaration
public void run()

Purpose
This method is implemented for interface java.lang.Runnable. It will be called when
you create this instance. You need not call this method.

TIB/Adapter for Web User’s Guide Page 175

com.tibco.portal.svcreg.APSvcImpl

APSvcImpl.sendHeartbeat()
RV 6.x only
Method

Declaration
public void sendHeartbeat()
throws com.tibco.tibrv.TibrvException

Purpose
Send a heartbeat, called internally, by responding to an announcement message from an
APSvcRegistry. You can invoke this method to explicitly send a heartbeat.

Page 176 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

APSvcImpl.startHeartbeating()
RV 6.x only
Method

Declaration
public void startHeartbeating()
throws com.tibco.tibrv.TibrvException

Purpose
Starts sending periodic heartbeats by activating a timer. The method is normally called by
APSvcImpl.run() and not typically called directly. This call should be invoked only after
a service instance is disabled and then enabled.

TIB/Adapter for Web User’s Guide Page 177

com.tibco.portal.svcreg.APSvcImpl

APSvcImpl.terminate()
RV 6.x only
Method

Declaration
public void terminate()
throws com.tibco.tibrv.TibrvException

Purpose
Inform all APSvcRegistry instances that this service instance has exited.

Page 178 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

Compiling the Service Examples

You must create the service example executables:

1. cd <install_path>/samples/rv6/java

2. Edit the Makefile to reflect your environment.

3. Type make or nmake (Microsoft utility).
4. This will make the executables for all the following examples.

TIB/Adapter for Web User’s Guide Page 179

Simple Service Java Example

Simple Service Java Example

This program allows you to specify the subject the service will listen for requests on, and
the string it will return.

Starting the Program

Start the program from the command line. For example:
> java SimpleSvc hello.world "Hello World"

If /servlet/TAW is the URL mapping in your web browser type:

http://<your web server>/servlet/TAW?subject=hello.world
The program will return a page containing hello to your web browser and the reply
message that it is sending to the servlet on the command line.

Source Code
The SimpleSvc.java file where the simple service is defined is listed next. In the code,
the basic steps are to:

All service instances must subclass TAWrvService and implement the abstract request
callback member function onMsg().

A TAWrvRequest object is created by TAW when a request is received and is delivered
to an application through the onMsg method. The reply member of TAWrvRequest is
used to transmit the reply string to the client.

In main, a SimpleSvc instance is first created. Then its request subject, and the string
to provide in the reply are set. Finally, requests are enabled.

TAWrvRequest object contain an invisible “return address” that is used by the reply
method to return data to the client through the servlet.

Page 180 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

SimpleSvc.java
import com.tibco.portal.gw.web.api.rv6.*;
import com.tibco.tibrv.*;

public class SimpleSvc extends TAWrvService

{
public static void main(String argv[])
{
try
{
if(argv.length != 2)
System.out.println("usage: java SimpleSvc <listen subject>
<reply string>");
else
{
Tibrv.open(Tibrv.IMPL_NATIVE);
SimpleSvc svc = new SimpleSvc();
svc.setRequestSubject(argv[0]);
svc.replyString = argv[1];
svc.enableRequests();
System.out.println("Listening on: " + argv[0]);
System.out.println("Replying with: " + argv[1]);
}
}
catch(Exception e)
{
System.out.println("main: "+e);
}
}

public SimpleSvc() throws TibrvException { super(); }

public void onMsg(TAWrvRequest request)

{
try
{
request.reply(replyString);
System.out.println("Reply Message: "+ request.getReplyMsg());
}
catch(Exception e)
{
System.out.println("onMsg: "+e);
}
}

private String replyString;

}

TIB/Adapter for Web User’s Guide Page 181

File Service Java Example

File Service Java Example

This shows how to transmit string or binary data and set HTTP reply headers.

Starting the Program

Start the program from the command line. For example, if /foo/bar.gif is a gif image
file, you can run:
> java FileSvc my.test.filesvc /foo/bar.gif image/gif

If /servlet/TAW is the URL mapping in your web browser type:

http://<your web server>/servlet/TAW?subject=my.test.filesvc
The program will return the gif image file to your browser.

Source Code
The FileSvc.java file where the simple service is defined is given next. In the code, the
basic steps are to:

All service instances must subclass TAWrvService and implement the abstract request
callback member function onMsg().

A TAWrvRequest object is created by TAW when a request is received and is delivered
to an application through the onMsg() method. The reply member of TAWrvRequest
is used to transmit the reply string to the client. An HTTP “content-type” reply
header is set from the command-line-specified value which should be chosen to reflect
the type of file. Next, the appropriate form of reply is used to transmit the file contents
back to the client.

In main, a SimpleSvc instance is created. The desired request subject and content type
are set from command line parameters. The specified file is loaded into a buffer, and if
it is either a .gif or .jpg file, the file is considered a binary file. Finally, requests are
enabled.

When a request is received, the contents of the file are returned to the client using the
appropriate form of reply() for the type of file.

Page 182 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

FileSvc.java
import java.io.*;
import com.tibco.portal.gw.web.api.rv6.*;
import com.tibco.tibrv.*;

public class FileSvc extends TAWrvService {

private static final String usageString = "usage: java FileSvc <listen
subject> <file path> <content-type>";
public static void main(String argv[]) {
try {
if(argv.length != 3)
System.out.println(usageString);
else {
// Create and initialize service
// open the tibrv in native mode...
Tibrv.open(Tibrv.IMPL_NATIVE);

FileSvc svc = new FileSvc();

svc.setRequestSubject(argv[0]);
svc. contentType = argv[2];
System.out.println("Listening on: " + argv[0]);
System.out.println("Replying with contents of: " + argv[1]);
System.out.println("with reply header: \"content-type: "
+ argv[2] + "\"");
// Read file into buffer
FileInputStream fis = new FileInputStream(argv[1]);
int bufsize = 10000;
svc.bytes = new byte[bufsize];
for( svc.bytesRead = fis.read(svc.bytes); svc.bytesRead ==
svc.bytes.length; svc.bytesRead = fis.read(svc.bytes))
{
bufsize *= 2;
svc.bytes = new byte[bufsize];
fis.close();
fis = new FileInputStream(argv[1]);
}
// Check for known types of binary files
svc.isBinaryFile = (argv[1].endsWith(".gif") ||
argv[1].endsWith(".jpg"));
// Start processing requests
svc.enableRequests();
}
}
catch(Exception e)
{
System.out.println("main: "+e);
}
}

public FileSvc() throws TibrvException { super(); }

public void onMsg(TAWrvRequest request) {

TIB/Adapter for Web User’s Guide Page 183

File Service Java Example

try {
request.setHttpReplyHeader("content-type", contentType);
if(isBinaryFile)
request.reply(bytes);
else
request.reply(new String(bytes));
} catch(Exception e) {
System.out.println("onMsg: "+e);
}
}
private int bytesRead;
private byte[] bytes;
private String contentType;
private boolean isBinaryFile;
}

Page 184 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

WorldHello Java Example

This is a service pool example. Depending on the command line argument given, the
service will return a language-specific greeting. If you run multiple instances of this
service, each replying in a different language, requests will be randomly distributed to
worker services by the RVDQ scheduler, and you will see greetings in different languages
if you make multiple requests.

Starting the Program

Start multiple instances of this program from the command line. For example:
> java WorldHello english &
> java WorldHello french &
> java WorldHello japanese &
This runs three instances in the background. The listen subject, taw.worldhello is
hardcoded into the program.
If /servlet/TAW is the URL mapping in your web browser type:
http://<your web server>/servlet/TAW?subject=taw.worldhello
Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser.

Source Code
The WorldHello.java file where the service pool is defined is given next. In the code, the
basic steps are to:

All service instances must subclass TAWrvService and implement the abstract request
callback member function onMsg().

Create an instance of WorldHello using the RVDQ session just created. Setup reply
data hash table and finally enable requests.

When a request is received, the onMsg() method looks up the appropriate greeting in
the hash table and invokes request's reply method to send it back to the client.

WorldHello.java
import java.util.*;

TIB/Adapter for Web User’s Guide Page 185

WorldHello Java Example

import com.tibco.portal.gw.web.api.rv6.*;
import com.tibco.tibrv.*;
public class WorldHello extends TAWrvService {
private static final String rvdqListenSubject = "taw.worldhello";
private static final String servicePool = "WorldHello";

public static void main(String argv[]) {

try {
if(argv.length != 1) {
System.out.println("usage: java WorldHello <language>");
System.out.println("language = english, french, or
japanese");
} else {
// open tibrv in native mode...
Tibrv.open(Tibrv.IMPL_NATIVE);

TibrvCmQueueTransport qt = new TibrvCmQueueTransport(

new TibrvRvdTransport(System.getProperty("SERVICE"),
System.getProperty("NETWORK"),
System.getProperty("DAEMON")),
servicePool);
// Instantiate World Hello Service and set up the
// default event queue
WorldHello svc = new WorldHello(qt, null, rvdqListenSubject);
svc.language = argv[0];
svc.greetings = new Hashtable();
svc.greetings.put("english", "Hello");
svc.greetings.put("french", "Bon jour");
svc.greetings.put("japanese", "Konnichiwa");
svc.enableRequests();
System.out.println("Listening on: "+ rvdqListenSubject);
}
} catch(Exception e) { System.out.println("main: "+ e); }
}

public WorldHello(TibrvCmQueueTransport s, TibrvQueue q, String subj)

throws TibrvException, TAWException {
super(s, q, subj);
}

public void onMsg(TAWrvRequest request) {

try {
String greeting = (String)this.greetings.get(this.language);
request.setHttpReplyHeader("content-type","text/plain");
if(greeting != null) request.reply(greeting);
else
request.reply("No greeting for language " + this.language);
} catch(Exception e) { System.out.println("onMsg: "+ e); }
}
private String language;
private Hashtable greetings;
}

Page 186 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

HelloGoodbye Java Example

This is another service pool example. This shows how an initial request can be directed to
a worker service by the RVDQ scheduler, and how the direct request subject is used to
bypass the RVDQ scheduler for subsequent requests from the same client. In addition to
returning a language-specific greeting like worldhello, this service also returns a
hyperlink that contains the direct request subject. When this hyperlink is clicked on, the
client communicates directly with the service instance that provide the greeting page.

Starting the Program

Start multiple instances of this program from the command line. For example:
> java HelloGoodbye english 0 &
> java HelloGoodbye french 1 &
> java HelloGoodbye japanese 2 &
This runs three instances in the background. The listen subject, taw.HelloGoodbye is
hardcoded into the program.
If /servlet/TAW is the URL mapping in your web browser type:
http://<your web server>/servlet/TAW?subject=taw.hellogoodbye
Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser,
depending upon which service handles your request.
If you now click on this link, a request will be sent back to the same service using its direct
request subject. The service will respond with goodbye in the same language it used
before. The last numeric argument is used to make a unique direct request subject.

Source Code
The HelloGoodbye.java file where the service pool is defined is given next. In the code,
the basic steps are to:

Subclass TAWrvService and implement the abstract request callback member
function onMsg().

Construct a unique direct request subject by concatenating the identifier specified on
the command line with the request subject and provide it to the service instance. Setup
the reply hash tables and finally enable requests.

TIB/Adapter for Web User’s Guide Page 187

HelloGoodbye Java Example

Initial requests from a client are delivered to the service through the onMsg() method.
This method builds an HTML page that consists of a hyperlink that displays as hello
or foreign language equivalent. The URL in this link embeds the direct request subject
so that when the link is followed, a request will be sent to the service's direct request
subject. This page is then returned to the client.

The onDirectMsg() method will never be invoked on the initial client request. It is
only invoked after the service has returned the hello page described above, and after
the user has clicked on the link. In response, the same language that was used to say
hello will be used to prepare a goodbye page.

HelloGoodbye.java
import java.util.*;
import com.tibco.portal.gw.web.api.rv6.*;
import com.tibco.tibrv.*;

public class HelloGoodbye extends TAWrvService {

private static final String rvdqListenSubject = "taw.hellogoodbye";
private static final String servicePool = "HelloGoodbye";

public static void main(String argv[]) {

try {
if(argv.length != 2) {
System.out.println("usage: java HelloGoodbye <language> <unique
id>");
System.out.println("language = english, french, or japanese");
System.exit(-1);
} else {
Tibrv.open(Tibrv.IMPL_NATIVE);

TibrvCmQueueTransport qt = new TibrvCmQueueTransport(

new TibrvRvdTransport(System.getProperty("SERVICE"),
System.getProperty("NETWORK"),
System.getProperty("DAEMON")),
servicePool);

// Concatenate unique id to request subject to form the direct

// request subject
String s = rvdqListenSubject + "." + argv[1];

//
// Instantiate HelloGoodbye Service and set up the default
// event queue
//
HelloGoodbye svc = new HelloGoodbye(qt, null, rvdqListenSubject, s);
svc.language = argv[0];

Page 188 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

svc.hellos = new Hashtable();

svc.hellos.put("english", "Hello");
svc.hellos.put("french", "Bon jour");
svc.hellos.put("japanese", "Konnichiwa");
svc.goodbyes = new Hashtable();
svc.goodbyes.put("english", "Goodbye");
svc.goodbyes.put("french", "Au revoir");
svc.goodbyes.put("japanese", "Sayonara");
svc.enableRequests();
System.out.println("Listening on: "+ rvdqListenSubject);
}
} catch(Exception e) { System.out.println("main: "+e); }
}

public HelloGoodbye(TibrvCmQueueTransport s, TibrvQueue q, String subj,

String directSubj)
throws TibrvException, TAWException {
super(s, q, subj, directSubj);
}

public void onDirectMsg(TAWrvRequest request) {

try {
request.setHttpReplyHeader("content-type", "text/html");
request.reply("<html><body><h2>" + (String)goodbyes.get(language)
+ "</h2></body></html>");
} catch(Exception e) { System.out.println("onDirectMsg() "+e); }
}

public void onMsg(TAWrvRequest request) {

try {
String hello = (String)this.hellos.get(this.language);
if(hello != null) {
String url = getDirectRequestSubject();
String s = "<html><body><a href=/servlet/TAW?subject=" + url + ">"
+ hello + "</a></body></html>";
request.setHttpReplyHeader("content-type", "text/html");
request.reply(s);
} else
request.reply("No hello for language " + this.language);
} catch(Exception e) { System.out.println("onMsg: "+e); }
}

private String language;

private Hashtable hellos;
private Hashtable goodbyes;
}

TIB/Adapter for Web User’s Guide Page 189

MultiDispatcher Service Java Example

MultiDispatcher Service Java Example

The multidispatcher service example illustrates how to create more than one dispatcher
thread to dispatch events from the queue. Typically one dispatcher thread is used to
dispatch events. By creating multiple dispatcher threads, it allows multiple requests to be
processed simultaneously.

Starting the Program

Java usage: java MultiDispatcher <listen subject> <number of dispatchers>
To run the example:
1. Start the service instance multipDispatcher. For example:
java MultiDispatcher taw.dispatch.one 1

java MultiDispatcher taw.dispatch.three 3

2. Modify task.html in the POST action=http://<server>/servlet/TAW

3. Create multiple browser windows with task.html (for example, three windows)
4. Fill in the subject taw.dispatch.one, job number, processing time. For example:
job number 1001, processing time 10

job number 1002, processing time 7

job number 1003, processing time 2

and submit the forms with jobs all at once (=1001,1002,1003 consecutively).
The sequence of replying from the browser is 1001,1002,1003 with the time displayed.
5. Replace the subject with taw.dispatch.three and submit the forms again.
You will notice the sequence of reply from the browser is in different order, most likely
1003, 1002, 1001 because the processing time for job number 1003 is the least and we have
three threads to handle the tasks.

Source Code
The MultiDispatcher.java file is defined is given next.
import com.tibco.portal.gw.web.api.rv6.*;

Page 190 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

import com.tibco.tibrv.*;
import java.util.*;

public class MultiDispatcher extends TAWrvService

{

public static void main(String argv[])

{
try
{

if(argv.length < 2 )
System.out.println("usage: java MultiDispatcher <listen subject>
<number of dispatchers>");
else
{
Tibrv.open(Tibrv.IMPL_NATIVE);

TibrvQueue queue = new TibrvQueue();

//
// Instantiate MultiDispatcherService, pass the new event queue
// to the constructor and have the constructor set up a
// transport object
//
MultiDispatcher svc = new MultiDispatcher((TibrvTransport)null,
queue, argv[0]);
System.out.println("Listening on : " + argv[0]);

int numDispatcher = (new Integer(argv[1])).intValue();

// Get the queue it is using

TibrvQueue tawQueue = svc.getDispatchQueue();

//
// Create more dispatcher threads and associate them to the queue.
// TAWrvService internally would create one dispatcher thread
//
for (int i=0; i<numDispatcher-1; i++) {
TibrvDispatcher dispatcher = new TibrvDispatcher(tawQueue);
}

svc.enableRequests();

}
}
catch(Exception e)
{
System.out.println("main: "+e);
}
}

public MultiDispatcher(TibrvTransport t, TibrvQueue q, String s)

TIB/Adapter for Web User’s Guide Page 191

MultiDispatcher Service Java Example

throws TibrvException, TAWException {

super(t,q,s);
}

public void waitSecs(int secs) throws Exception {

TibrvQueue _queue = new TibrvQueue();
_queue.timedDispatch(secs);
}

public void onMsg(TAWrvRequest request)

{
String jobid;
String replyStr = "Job id or processing time is not valid.";
String processingTimeStr;
int processingTime;
try
{
int i,n;
jobid = request.getUrlParameter("jobid");
processingTimeStr = request.getUrlParameter("processingTime");

if (processingTimeStr != null && jobid != null) {

processingTime = (new Integer(processingTimeStr)).intValue();

if (processingTime > -1 && jobid != null) {

waitSecs(processingTime);
Date responseTime = new Date();
replyStr = "Finish processing job "+jobid+ " [process time="+
processingTime+"s] at "+ responseTime;
}
}

request.setHttpReplyHeader("content-type","text/plain");
request.reply(replyStr);
}
catch(Exception e)
{
System.out.println("onMsg: "+e);
}
}

private String replyString;

}

Page 192 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

Simple Service Registry Java Example

The simple service registry example demonstrates the service registry functionality of the
servlet. For example, when you start three programs,

simplesvcReg svc server.1 "response from server 1"

simplesvcReg svc server.2 "response from server 2"

simplesvcReg svc server.3 "response from server 3"

The programs register to the servlet as the service svc and listen on request subjects of
server.1, server.2, and server.3.

When you issue URL=http://<server>/servlet/TAW?service=svc in the browser, the

servlet chooses among the services that belong to the service name svc and selects one of
them based on its mechanism (load-balancing criteria, or application specific criteria) and
returns a message to the browser.

Starting the Program

Java usage: java SimpleSvcReg <service name> <service subject> <reply string> [<heartbeat
subject> <announce subject>]

heartbeat subject is the heartbeat subject name the service instance is publishing
constantly, telling the servlet that it is up for service,

announce subject is the announce subject name that the servlet announces itself that it is
up, so that service instance will be aware and send a heartbeat in response to the
announce.
If the two subjects are not specified, the default is used.

Source Code
The SimpleSvcReg.java file is given next.
import com.tibco.portal.svcreg.*;
import com.tibco.portal.gw.web.api.rv6.*;
import com.tibco.tibrv.*;

public class SimpleSvcReg extends TAWrvService

{
public static void main(String argv[])
{
try

TIB/Adapter for Web User’s Guide Page 193

Simple Service Registry Java Example

{
if(argv.length < 3)
System.out.println("usage: java SimpleSvcReg <service name>
<service subject> <reply string> [<heartbeat subject>
<announce subject>]");
else
{
Tibrv.open(Tibrv.IMPL_NATIVE);

double hbInt = 5.0; // heartbeat interval in secs, intervals

// between each heartbeat
double failInt = 11.0; // failure interval in secs, (period that
// servlet should declare
// it is out of service)

String hbSubj = (argv.length > 3 ) ? argv[3] : "TAW.heartbeat";

// heartbeat subject
String annSubj = (argv.length > 4) ? argv[4] : "TAW.announce";
// announce subject

SimpleSvcReg svc = new SimpleSvcReg(argv[0], argv[1], hbSubj,

annSubj, hbInt, failInt, APSvcConstants.enabled);

svc.setRequestSubject(argv[1]);
svc.replyString = argv[2];
System.out.print("Service name = " + argv[0]);
System.out.print(", Heartbeat subject = " + hbSubj);
System.out.println(", Announce subject = "+ annSubj);
System.out.println("Listening on : " + argv[1]);
System.out.println("Replying with : " + argv[2]);
svc.enableRequests();
}
}
catch(Exception e)
{
System.out.println("main: "+e);
}
}

public SimpleSvcReg() throws TibrvException { super(); }

public SimpleSvcReg(String svcName, String svcSubj, String hbSubj,

String annSubj, double hbInt, double failInt, byte enabledStatus)

throws TibrvException
{
super();
try
{
// Start object to handle service registry
serviceRegistry = new APSvcImpl(svcName, svcSubj, getTibrvTransport(),
hbSubj, hbInt, failInt, annSubj, enabledStatus);

Page 194 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

new Thread(serviceRegistry).start();
}
catch(Exception e)
{
System.out.println("SimpleSvcReg: "+e);
}
}

public void onMsg(TAWrvRequest request)

{
try
{
request.reply(replyString);
}
catch(Exception e)
{
System.out.println("onMsg: "+e);
}
}

private String replyString;

private APSvc serviceRegistry;
}

TIB/Adapter for Web User’s Guide Page 195

Raw Service Java Example

Raw Service Java Example

The RawSvc service demonstrates using TIB/Rendezvous directly instead of using the
TAW API. The RawSvc service is similar to the Simple service. The program takes in a list
of subjects it is listening on and a reply message. For example, java RawSvc "a.b.c"
"x.y.z" "Hello". Then, when you submit a request from the browser making the subject
equal to either one of them, you will receive a response of "Hello" from the browser
together with the timestamp of when the service replies.

Starting the Program

Java usage: java RawSvc <subject-list> <reply Message>

Some platforms require proper quoting of the arguments to prevent the command line
processor from modifying the command arguments. You can terminate the program by
typing Control-C.
You can specify communication parameters for tibrvTransport_Create(). If none are
specified the following defaults are used:
service "rendezvous" or "7500/udp"
network the result of gethostname()
daemon "tcp:7500"

For example:

To listen to every message published on subject a.b.c:
java RawSvc a.b.c

To listen to every message published on subjects a.b.c and x.*.Z:

java RawSvc a.b.c "x.*.Z"

To listen to every system advisory message:

java RawSvc "_RV.*.SYSTEM.>"

To listen to messages published on subject a.b.c using port 7566:

java RawSvc -service 7566 a.b.c

Page 196 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

Source Code
The RawSvc.java file is given next.
import java.util.*;
import com.tibco.tibrv.*;
import com.tibco.portal.gw.web.*;

public class RawSvc implements TibrvMsgCallback

{

String service = null;

String network = null;
String daemon = null;
String replyMsg = null;

public RawSvc(String args[])

{
// Parse arguments for possible optional
// parameters. These must precede the subject
// and message strings
int i = get_InitParams(args);

// Must have at least one subject

if (i >= args.length)
usage();

replyMsg = args[args.length-1];
// Open Tibrv in native implementation
try
{
Tibrv.open(Tibrv.IMPL_NATIVE);
}
catch (TibrvException e)
{
System.err.println("Failed to open Tibrv in native
implementation:");
e.printStackTrace();
System.exit(0);
}

// Create RVD transport

TibrvTransport transport = null;
try
{
transport = new TibrvRvdTransport(service,network,daemon);
}
catch (TibrvException e)
{
System.err.println("Failed to create TibrvRvdTransport:");
e.printStackTrace();
System.exit(0);
}

TIB/Adapter for Web User’s Guide Page 197

Raw Service Java Example

// Create listeners for specified subjects

while (i < args.length)
{
// Create listener using default queue
try
{
new TibrvListener(Tibrv.defaultQueue(),
bthis,transport,args[i],null);
System.err.println("Listening on: "+args[i]);
}
catch (TibrvException e)
{
System.err.println("Failed to create listener:");
e.printStackTrace();
System.exit(0);
}
i++;
}

// Dispatch Tibrv events

while(true)
{
try
{
Tibrv.defaultQueue().dispatch();
}
catch(TibrvException e)
{
System.err.println("Exception dispatching default queue:");
e.printStackTrace();
System.exit(0);
}
catch(InterruptedException ie)
{
System.exit(0);
}
}
}

private void setAE30WireFormatFields(TibrvMsg TibrvMsg) throws

TibrvException
{
TibrvMsg.add(TAWrvMsgFLD.PFMT, (short)TAWrvMsgFLD.AE_PFMT);
TibrvMsg.add(TAWrvMsgFLD.VER, (short)TAWrvMsgFLD.AE_VER);
TibrvMsg.add(TAWrvMsgFLD.TYPE, (short)TAWrvMsgFLD.AE_STRING_TYPE);
}

private TibrvMsg packageTAWreply(String msg) {

try {
TibrvMsg TibMsg = new TibrvMsg();
setAE30WireFormatFields(TibMsg);

Page 198 TIB/Adapter for Web User’s Guide

 Chapter 6 Java API Reference for TIB/Rendezvous 6.x

msg += "\n"+(new java.util.Date().toString());

TibMsg.add(TAWrvMsgFLD.HTTP_STATUS_CODE, 200);
TibMsg.add(TAWrvMsgFLD.HTTP_REASON_PHRASE, "OK");
TibMsg.add(TAWrvMsgFLD.VERSION_CODE, 40);
TibMsg.add(TAWrvMsgFLD.ENTITY_BODY, msg);

return TibMsg;
} catch (Exception e) {
return null;
}
}

public void onMsg(TibrvListener listener, TibrvMsg msg)

{
TibrvMsg reply = null;
try {
reply = packageTAWreply(replyMsg);
listener.getTransport().sendReply(reply, msg);
System.out.println((new java.util.Date()));
} catch (Exception e) {
System.out.println("onMsg: " + e);
}
}

// Print usage information and quit

void usage()
{
System.err.println("Usage: java RawSvc [-service service]
[-network network]");
System.err.println("[-daemon daemon] <subject-list> <reply
Message>");
System.exit(-1);
}

int get_InitParams(String[] args)

{
int i=0;
while(i < args.length-1 && args[i].startsWith("-"))
{
if (args[i].equals("-service"))
{
service = args[i+1];
i += 2;
}
else
if (args[i].equals("-network"))
{
network = args[i+1];
i += 2;
}
else
if (args[i].equals("-daemon"))

TIB/Adapter for Web User’s Guide Page 199

Raw Service Java Example

{
daemon = args[i+1];
i += 2;
}
else
usage();
}
return i;
}

public static void main(String args[])

{
new RawSvc(args);
}

Page 200 TIB/Adapter for Web User’s Guide

Appendix A C++ API Reference for
TIB/Rendezvous 5.x

This appendix describes the C++ API used with TIB/Rendezvous 5.x. Use this API to
write TIB/Adapter for Web service instances when linking to TIB/Rendezvous 5.x. With
this API you can also create a service pool and use TIB/Rendezvous distributed queues to
load-balance requests to service pool members.
Note: The TAW C++ API for TIB/Rendezvous 5.x is not supported on Windows NT.

Topics

Overview, page 202

TAWrvService, page 204

TAWrvRequest, page 221

C++ Example Service Instances for TIB/Rendevous 5.x, page 243

TIB/Adapter for Web User’s Guide Page 201

Overview

Overview

Use this API to write TIB/Adapter for Web service and service-pool applications. It
provides the capability to easily use TIB/Rendezvous version 5.3 distributed queues to
load-balance requests to service pool members.
The TIB/Adapter for Web distribution contains sample source programs that illustrate
how to write very simple applications as well as more complex RVDQ-based services.
Copies of the sample programs are included in your installation area in the samples
directory.

The Basics
Your TIB/Adapter for Web service instances must perform the following basic steps:
1. Include rv5/TAWrv.h
2. Create a subclass of TAWrvService that implements TAWrvService::onRequest().
Inside onRequest(), arrange for one of the TAWrvRequest::reply() methods to
return data to the servlet.
3. Instantiate your TAWrvService subclass in your main program, and then call its
enableRequests() method to begin listening for requests.

The example programs, simplesvc.cc and filesvc.cc illustrate this basic structure.
They also show how to handle non-text data and manipulate HTTP reply headers. Source
listings are provided in section C++ Example Service Instances for TIB/Rendevous 5.x on
page 243.

Service Pools
In some applications, the request rate can exceed the capacity of a single service instance.
A service pool is a fault-tolerant and load-balanced collection of services.
TIB/Rendezvous Distributed Queues (RVDQ) ensure that a request is delivered to only
one pool member. The TAW C++ API makes it very convenient to set up service pools.
For more information on setting up service pools, see RVDQ Service Pools on page 324.

Page 202 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

Classes
There are only two classes that you need to know about to use the C++ API:

TAWrvService

TAWrvRequest
You must create your own subclass of TAWrvService. The onRequest() or
onDirectRequest() methods of this subclass will receive TAWrvRequest objects which
contain all of the HTTP information about the request as well as any data.

TIB/Adapter for Web User’s Guide Page 203

TAWrvService

TAWrvService
RV 5.x only
Class

Purpose
TAWrvService is an abstract class. Your application needs to create a subclass of
TAWrvService that implements the request callbacks that will be invoked when requests
are received.

Remarks
There are two constructors. The first constructor is used to build standard,
non-load-balancing service instances, using an RvSession. The second constructor is used
to build load-balancing service instances based on TIB/Rendezvous distributed queues,
using an RvCmqSession. If directSubject is specified, requests may be sent directly to
this service instance using that subject, bypassing the RVDQ scheduler.

Member Summary

Name Description Page

TAWrvService::TAWrvService() Constructor 206

TAWrvService::~TAWrvService() Destructor 208

TAWrvService::onRequest() Invoked in response to 209

requests received on the
standard request subject.

TAWrvService::onDirectRequest() Invoked in response to 210

requests received on the direct
request subject.

TAWrvService::setRequestSubject() Set subject associated with 211

onRequest()

TAWrvService::setDirectRequestSubje Set subject associated with 212

ct()
onDirectRequest()

TAWrvService::getDirectRequestSubje Get the subject is associated 213

ct()
with onDirectRequest()

Page 204 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

Name Description Page

TAWrvService::getRequestSubject() Get the subject is associated 214

with onRequest()

TAWrvService::enableRequests() Start listening for requests 215

TAWrvService::disableRequests() Stop listening requests 216

TAWrvService::isEnabled() Return true if requests are 217

enabled

TAWrvService::isValid() Return true if this 218

TAWrvSession object is valid

TAWrvService::getRvSession() Return the C language API 219

Rendezvous session
encapsulated by the C++
RvSession in use

TAWrvService::getErrorMsg() Return a description of the 220

error that occurred. Most
useful when the constructor
fails.

TIB/Adapter for Web User’s Guide Page 205

TAWrvService

TAWrvService::TAWrvService()
RV 5.x only
Constructor

Declaration
TAWrvService(RvSession* pRvSession=0,
const char* requestSubject=0);

TAWrvService(RvCmqSession* pRvCmqSession,
const char* requestSubject=0,
const char* directRequestSubject=0);

Purpose
All applications must provide a subclass of TAWrvService that implements the
onRequest method. The first constructor is used to setup normal reliable communications
between the servlet and your application. The second constructor is used to build
RVDQ-based service pools.

Remarks
Subjects need not be specified here, but must be set prior to enabling the service.

Page 206 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

Parameters

Name Description

pRvSession Optional RvSession to use. If none is specified, a default

RvSession will be constructed. You may tailor this session
by using the RVSESSION, RVNETWORK, and
RVDAEMON environment variables.

pRvCmqSession RVDQ session. You must construct one and provide it to

the constructor.

requestSubject Subject name that the application will be listening for

requests on. All RVDQ-based service pool members listen
to this subject, but RVDQ guarantees delivery to only one
member.

directRequestSubject For RVDQ-based applications, this is a secondary subject

name used to provide direct access to a service pool
member.

Example
class SimpleService : public TAWrvService
{
public:
SimpleService(RvSession *pRvSession, const char* requestSubject,
const char* replyString)
: TAWrvService(pRvSession, requestSubject),
_replyString(replyString){};
~SimpleService(){};
void onRequest(TAWrvRequest* request);
private:
const char* _replyString;
};

Errors
Use the isValid() member to make sure that the constructor did not fail. For a
descriptive error message string, use the TAWrvService::getErrorMsg() member.

See Also
TAWrvService::isValid(), page 218.
TAWrvService::getErrorMsg(), page 220.

TIB/Adapter for Web User’s Guide Page 207

TAWrvService

TAWrvService::~TAWrvService()
RV 5.x only
Destructor

Declaration
~TAWrvService();

Purpose
This method destroys the TAWrvService instance from which it is called and releases all
resources.

Remarks
This destructor must be called whenever you are finished with communications between
the servlet and your application.
Parameters
None.

Page 208 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvService::onRequest()
RV 5.x only
Method

Declaration
virtual void onRequest(TAWrvRequest* pRequest) = 0;

Purpose
All applications must provide a subclass of TAWrvService that implements the
onRequest method. This method is called when a request is received.

Parameters

Name Description

pRequest Pointer to the TAWrvRequest object that encapsulates all data,

header and return address information associated with the
request.

TIB/Adapter for Web User’s Guide Page 209

TAWrvService

TAWrvService::onDirectRequest()
RV 5.x only
Method

Declaration
virtual void onDirectRequest(TAWrvRequest* pRequest);

Purpose
This method is only relevant to RVDQ-based service instances. This method is called
when a request is received on the direct request subject. Requests to direct request
subjects are not intercepted by the RVDQ scheduler. The default implementation merely
invokes the onRequest() method.

Parameters

Name Description

pRequest Pointer to the TAWrvRequest object that encapsulates all data,

header and return address information associated with the
request.

Page 210 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvService::setRequestSubject()
RV 5.x only
Method

Declaration
virtual void setRequestSubject(const char* subjectName);

Purpose
Set the subject name used to listen for requests. This subject is used by both RVDQ-based
pooled services, or by singleton applications.

Parameters

Name Description

subjectName Rendezvous subject name that the service will use to listen for
requests.

TIB/Adapter for Web User’s Guide Page 211

TAWrvService

TAWrvService::setDirectRequestSubject()
RV 5.x only
Method

Declaration
virtual void setDirectRequestSubject(const char* subjectName);

Purpose
Set the subject name used to listen for requests directed at a specific member or members
of an RVDQ-based service pool. This subject is not used by RvSession-based services at
all. RVDQ-based applications can use this subject to get requests without the intervention
of the RVDQ scheduler.

Parameters

Name Description

subjectName RV subject name that the service will use to listen for direct
requests.

Page 212 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvService::getDirectRequestSubject()
RV 5.x only
Method

Declaration
virtual const char* getDirectRequestSubject();

Purpose
Get the subject name used to listen for requests directed at a specific member or members
of an RVDQ-based service pool. This subject is not used by RvSession-based services at
all. RVDQ-based applications can use this subject to get requests without the intervention
of the RVDQ scheduler.

Parameters
Returns a pointer to the subject name string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 213

TAWrvService

TAWrvService::getRequestSubject()
RV 5.x only
Method

Declaration
virtual const char* getRequestSubject();

Purpose
Get the subject name used to listen for requests. This subject is used by both RVDQ-based
pooled services, or by singleton applications.

Parameters
Returns a pointer to the subject name string or NULL. Do not modify or delete this string.

Page 214 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvService::enableRequests()
RV 5.x only
Method

Declaration
virtual rv_Boolean enableRequests();

Purpose
Start listening for requests.

Remarks
Prior to invoking enableRequests(), you must set the subjects on which your service
will accept requests. You can do this in the constructor, or use the setRequestSubject()
and setDirectRequestSubject(). This method creates RvListeners that remain valid
until the disableRequests() method is invoked.

Parameters
Returns RV_TRUE if successful, RV_FALSE otherwise.

See Also
TAWrvService::setRequestSubject(), page 211.
TAWrvService::setDirectRequestSubject(), page 212.
TAWrvService::disableRequests(), page 216.

TIB/Adapter for Web User’s Guide Page 215

TAWrvService

TAWrvService::disableRequests()
RV 5.x only
Method

Declaration
virtual rv_Boolean disableRequests();

Purpose
Stop listening for requests.

Remarks
This method destroys the RvListeners created in enableRequests().

Parameters
Returns RV_TRUE if successful, RV_FALSE otherwise.

Page 216 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvService::isEnabled()
RV 5.x only
Method

Declaration
virtual rv_Boolean isEnabled();

Purpose
Determine whether the service is currently listening for requests.

Parameters
Returns RV_TRUE if the service is currently listening for requests, RV_FALSE otherwise.

TIB/Adapter for Web User’s Guide Page 217

TAWrvService

TAWrvService::isValid()
RV 5.x only
Method

Declaration
virtual rv_Boolean isValid();

Purpose
Provide a way for the TAWrvService constructor to report that it failed.

Remarks
Use the getErrorMsg() to determine the reason for the failure.

Parameters
Returns RV_TRUE if the object could be correctly built, RV_FALSE otherwise.

See Also
TAWrvService::getErrorMsg(), page 220.

Page 218 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvService::getRvSession()
RV 5.x only
Method

Declaration
rv_Session getRvSession();

Purpose
Get the TIB/Rendezvous C language session handle.

Parameters
Returns a pointer to rv_Session embedded in the RvSession object in use.

TIB/Adapter for Web User’s Guide Page 219

TAWrvService

TAWrvService::getErrorMsg()
RV 5.x only
Method

Declaration
virtual const char* getErrorMsg();

Purpose
Get a string describing what went wrong during an invocation of a TAWrvService
method.

Parameters
Returns a pointer to error description string or NULL.

Page 220 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest
RV 5.x only
Class

Purpose
TAWrvRequest objects are manufactured when requests are received. They encapsulate all
of the HTTP information in the request, including the communication endpoint to reply
to. Members can be used to access HTTP request information, as well as to prepare a
reply.

Remarks
These objects are created and destroyed by the API and are valid for the duration of one
invocation of your application’s implementation of TAWrvService::onRequest(). You
must copy any data or header information if your application will need them after
onRequest() returns.

Member Summary

Name Description Page

TAWrvRequest::getReplySubje Get the reply subject address used to 223

ct()
transmit the reply to the servlet.

TAWrvRequest::getUrlPath() Extract the path component from the 224

URL in the HTTP request line.

TAWrvRequest::getUrlResourc Extract the name of the resource from the 225

e()
URL in the HTTP request line.

TAWrvRequest::getHttpMethod Return the HTTP method from the HTTP 226

()
request line.

TAWrvRequest::getHttpUri() Return the HTTP URI from the HTTP 227

request line.

TAWrvRequest::getHttpVersio Return the HTTP version from the HTTP 228

n()
request line.

TAWrvRequest::getHttpReques Get the HTTP entity body (i.e. POST 229

tEntityBody()
data) from the request.

TIB/Adapter for Web User’s Guide Page 221

TAWrvRequest

Name Description Page

TAWrvRequest::getUrlParamet Lookup the value of a URL query 230

er()
parameter by name.

TAWrvRequest::getUrlParamet Return the URL query parameters as an 241

ers()
RvMsg

TAWrvRequest::getHttpReques Lookup the value of a specified HTTP 231

tHeader()
request header.

TAWrvRequest::getHttpReques Return the HTTP request headers as an 242

tHeaders()
RvMsg.

TAWrvRequest::setHttpReplyE Determine the reply payload. 232

ntityBody()

TAWrvRequest::setHttpReplyH Add a header to the reply. 233

eader()

bTAWrvRequest::setHttpStatu Set the reply status code in the HTTP 234

sCode()
status line.

TAWrvRequest::getRvdqSender Get the RVDQ sender name from the 235

Name()
request.

TAWrvRequest::getRvdqSequen Get the RVDQ sequence number from the 236

ceNumber()
request.

TAWrvRequest::reply() Marshall reply and send to servlet. 237

TAWrvRequest::getProtocolVe Get the TIB/Adapter for Web protocol 238

rsion()
version.

TAWrvRequest::setHttpReason Set the reply reason phrase the HTTP 239

Phrase()
status line.

TAWrvRequest::isValid() Tests object validity. Useful for detecting 240

failures during a TAWrvRequest
constructor.

Page 222 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getReplySubject()
RV 5.x only
Method

Declaration
virtual const char* getReplySubject();

Purpose
Get the subject name that the TIB/Adapter for Web servlet is listening for your reply on.

Parameters
Returns a pointer to the subject name string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 223

TAWrvRequest

TAWrvRequest::getUrlPath()
RV 5.x only
Method

Declaration
virtual const char* getUrlPath();

Purpose
Get the path from the URL in the HTTP request line. For example, if the URL is
//foo/bar/baz.htm, the path is //foo/bar.

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

Page 224 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getUrlResource()
RV 5.x only
Method

Declaration
virtual const char* getUrlResource();

Purpose
Get the path from the URL in the HTTP request line. For example, if the URL is
//foo/bar/baz.htm, the resource is baz.htm.

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 225

TAWrvRequest

TAWrvRequest::getHttpMethod()
RV 5.x only
Method

Declaration
virtual const char* getHttpMethod();

Purpose
Get the HTTP method from the request line.

Parameters
Returns a pointer to either GET or POST or NULL. Do not modify or delete this string.

Page 226 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getHttpUri()
RV 5.x only
Method

Declaration
virtual const char* getHttpUri();

Purpose
Get the HTTP URI from the request line. For example /foo/bar/baz.htm

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 227

TAWrvRequest

TAWrvRequest::getHttpVersion()
RV 5.x only
Method

Declaration
virtual const char* getHttpVersion();

Purpose
Get the HTTP version string from the request line. For example: HTTP/1.0

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

Page 228 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getHttpRequestEntityBody()
RV 5.x only
Method

Declaration
virtual const char* getHttpRequestEntityBody();

Purpose
Get the HTTP entity body from the request. This is where the POST data is.

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 229

TAWrvRequest

TAWrvRequest::getUrlParameter()
RV 5.x only
Method

Declaration
virtual const char* getUrlParameter(const char* name);

Purpose
Gets the value of a parameter in the URL query string by name. The lookup is case
sensitive.

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

Page 230 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getHttpRequestHeader()
RV 5.x only
Method

Declaration
virtual const char* getHttpRequestHeader(const char* name);

Purpose
Gets the value of a request header by name. The lookup is case insensitive.

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 231

TAWrvRequest

TAWrvRequest::setHttpReplyEntityBody()
RV 5.x only
Method

Declaration
virtual void setHttpReplyEntityBody(const char* body);
virtual void setHttpReplyEntityBody(const char* body, unsigned long
bodyLen);

Purpose
Set the HTTP reply entity body. This is where the reply data gets set. The first form is used
to return a string. The second form is used to return binary data such as images.

Parameters

Name Description

body A pointer to either a null-terminated string or a buffer of binary

data.

bodyLen The number of bytes in the body.

Page 232 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::setHttpReplyHeader()
RV 5.x only
Method

Declaration
virtual void setHttpReplyHeader(const char*name, const char* value);
virtual void setHttpReplyHeader(const char* name, int value);

Purpose
Set a HTTP reply header to either a string or an integer.

Parameter

Name Description

name The name of the header to insert.

value The string or integer value of the header.

TIB/Adapter for Web User’s Guide Page 233

TAWrvRequest

bTAWrvRequest::setHttpStatusCode()
RV 5.x only
Method

Declaration
virtual void setHttpStatusCode(int code);

Purpose
Set a HTTP reply status code.

Parameters

Name Description

code The HTTP return code

Page 234 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getRvdqSenderName()
RV 5.x only
Method

Declaration
virtual const char* getRvdqSenderName();

Purpose
Get the name of the RVDQ sender. This is only relevant to RVDQ-based service instances.

Parameters
Returns a pointer to the string or NULL. Do not modify or delete this string.

TIB/Adapter for Web User’s Guide Page 235

TAWrvRequest

TAWrvRequest::getRvdqSequenceNumber()
RV 5.x only
Method

Declaration
rvcm_Seq getRvdqSequenceNumber();

Purpose
Get the RVDQ sequence number of this request message. This is only relevant to
RVDQ-based service instances.

Parameters
Returns the sequence number.

Page 236 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::reply()
RV 5.x only
Method

Declaration
rv_Boolean reply();

rv_Boolean reply(const char* entityBody,

unsigned long entityBodyLen,
int statusCode = 200,
const char* reasonPhrase = "OK");

rv_Boolean reply(const char* entityBody,

int statusCode = 200,
const char* reasonPhrase = "OK");

Purpose
These methods marshall parameters from the TAWrvRequest into an RvMsg and send
them back to the requesting servlet. The first form assumes that all reply headers and data
have been stored using TAWrvRequest set methods. The remaining two forms are for
convenience. The second form is for sending binary data, and the third form is for sending
strings.

Parameters

Name Description

entityBody The desired reply entity body. Either a string or buffer of binary
data, depending on whether entityBodyLen is specified.

entityBodyLen The length of binary data buffer.

statusCode The HTTP status code.

reasonPhase The HTTP reason phrase.

TIB/Adapter for Web User’s Guide Page 237

TAWrvRequest

TAWrvRequest::getProtocolVersion()
RV 5.x only
Method

Declaration
int getProtocolVersion();

Purpose
Get the TIB/Adapter for Web version number.

Parameters
Returns the version number.

Page 238 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::setHttpReasonPhrase()
RV 5.x only
Method

Declaration
virtual void setHttpReasonPhrase(const char* phrase);

Purpose
Set a HTTP reply reason phrase; for example, OK.

Parameters

Name Description

phrase The descriptive phrase that accompanies the HTTP reply status
code.

TIB/Adapter for Web User’s Guide Page 239

TAWrvRequest

TAWrvRequest::isValid()
RV 5.x only
Method

Declaration
rv_Boolean isValid();

Purpose
Tests object validity. Useful for detecting failures during a TAWrvRequest constructor.

Parameters
None.

Example
TAWrvRequest* pRequest
= new TAWrvRequest(subject, replySender, rDatum, invoker);
if(!pRequest->isValid())
{
pImpl->_errorMsg = “Bad datum”;
#if DEBUG
printf(“TAWrvServiceRequestCallback::onData %s\n”, pImpl->_errorMsg);
rDatum.print();
printf(“\n”);
#endif
}
else
pImpl->_rTAWrvService.onRequest(pRequest);
delete pRequest;

Page 240 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

TAWrvRequest::getUrlParameters()
RV 5.x only
Method

Declaration
const RvMsg& getUrlParameters();

Purpose
Return the URL query parameters as an RvMsg.

Parameters
None.

TIB/Adapter for Web User’s Guide Page 241

TAWrvRequest

TAWrvRequest::getHttpRequestHeaders()
RV 5.x only
Method

Declaration
const RvMsg& getHttpRequestHeaders();

Purpose
Return the HTTP request headers as an RvMsg.

Parameters
None.

Page 242 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

C++ Example Service Instances for TIB/Rendevous 5.x

Four example C++ programs are provided with TIB/Adapter for Web:

simplesvc.cc. This is a glorified Hello World program that allows you to specify the
subject the service will listen for requests on, and the string it will return.

filesvc.cc. This shows how to transmit string or binary data and set HTTP reply
headers.

worldhello.cc. This is a service pool example. Depending on the command line
argument given, the service will return a language-specific greeting. If you run
multiple instances of this service, each replying in a different language, requests will
be randomly distributed to worker services by the RVDQ scheduler, and you will see
greetings in different languages if you make multiple requests.

hellogoodbye.cc. This is another service pool example. This shows how an initial
request can be directed to a worker service by the RVDQ scheduler, and how the
direct request subject is used to bypass the RVDQ scheduler for subsequent requests
from the same client. In addition to returning a language-specific greeting like
worldhello.cc, this service also returns a hyperlink that contains the direct request
subject. When this hyperlink is clicked, the client communicates directly with the
service instance instance that provided the greeting page. This idiom is useful when
you need to maintain a session between client and service, as well as between fault
tolerant and load balanced services.

Compiling the Service Examples

You must create the service example executables:
1. cd <install_path>/samples/rv5/cpp

2. Edit the Makefile to reflect your environment.

3. Type make or nmake (Microsoft utility).
4. This will make the executables for all the following examples.

TIB/Adapter for Web User’s Guide Page 243

C++ Example Service Instances for TIB/Rendevous 5.x

simplesvc.cc
RV 5.x only
Note the following:

You must derive a subclass from TAWrvService that provides an implementation of

the abstract method onRequest.

The onRequest method is invoked by TAW whenever a request is received. This
implementation returns the string specified on the command line when the program
was invoked to the client.

Create an instance of SimpleService that uses command line parameters to
determine what subject to accept requests on, and what string to return in response to
a request.

After instantiating your TAWrvService subclass, you should make sure that it is valid
before proceeding further. The isValid method is used for this purpose.

If the object is not valid, the reason may be determined by invoking the getErrorMsg
method.

Start request processing.

Code Listing
#include "rv5/TAWrv.h"
#include "stdlib.h"
#include "string.h"

class SimpleService : public TAWrvService

{
public:
SimpleService(RvSession *pRvSession, const char* requestSubject,
const char* replyString)
: TAWrvService(pRvSession, requestSubject),
_replyString(replyString){};
~SimpleService(){};
void onRequest(TAWrvRequest* request);
private:
const char* _replyString;
};

void
SimpleService::onRequest(TAWrvRequest* pRequest)
{
pRequest->reply(_replyString);
}

int main(int argc, char** argv)

{

Page 244 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

if(argc < 3)
{
printf("usage: %s <listen subject> <reply string>\n", argv[0]);
exit(-1);
}
char* subject = argv[1];
char* replyString = argv[2];

printf("listening on: %s\nreplying with: \"%s\"\n",

subject, replyString);

/* Instantiate SimpleService and have constructor setup a RvSession. */

SimpleService simpleService((RvSession*)0, subject, replyString);
if(!simpleService.isValid())
{
printf("TAWrvService constructor failed. %s\n",
simpleService.getErrorMsg());
return -1;
}
/* Start listening for requests */
if(! simpleService.enableRequests() )
printf("Unable to enable request processing: %s\n",
simpleService.getErrorMsg());
else
rv_MainLoop(simpleService.getRvSession());
return -1;
}

Example Usage
Start the program from the command line. For example:
> simplesvc my.test.simplesvc hello

In your browser request:

http://<your web server>/servlet/TAW?subject=my.test.simplesvc

The program will return a page containing "hello" to your browser.

TIB/Adapter for Web User’s Guide Page 245

C++ Example Service Instances for TIB/Rendevous 5.x

filesvc.cc
RV 5.x only
Note the following:

You must derive a subclass from TAWrvService that provides an implementation of

the abstract method onRequest.

The onRequest method is invoked by TAW whenever a request is received. This
implementation returns the file specified on the command line and adds the
“content-type” HTTP header value that was also specified on the command line.

Create an instance of FileService that uses command line parameters to determine
what subject to accept requests on, which file to return, and the HTTP content-type.

After instantiating your TAWrvService subclass, you should make sure that it is
healthy before proceeding further. The isValid method is used for this purpose.

If the object is not valid, the reason may be determined by invoking the getErrorMsg
method.

Start request processing.

Code Listing
#include "rv5/TAWrv.h"
#include "stdlib.h"
#include "string.h"

const char* binaryExts[] =

{
".gif",
".jpg",
0
};

int isBinaryFile(const char* fileName)

{
int len = ::strlen(fileName);
char *p = (char*)fileName + (len - 4);
for(int i=0; binaryExts[i] ; i++)
{
if(strcmp(binaryExts[i], p) == 0)
return 1;
}
return 0;
}

class FileService : public TAWrvService

{
public:

Page 246 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

FileService(RvSession *pRvSession, const char* requestSubject,

const char* filePath, const char* contentType);
~FileService();
void onRequest(TAWrvRequest* request);
private:
const char* _filePath;
const char* _contentType;
char* _data;
unsigned long _dataLen;
rvmsg_Type _dataRvmsgType;
};

FileService::FileService(RvSession *pRvSession, const char*

requestSubject, const char* filePath, const char* contentType)
: TAWrvService(pRvSession, requestSubject),
_filePath(filePath), _contentType(contentType),
_data(0), _dataLen(0), _dataRvmsgType(RVMSG_STRING)
{
FILE* fp = fopen( _filePath, "rb" );
if(!fp)
{
printf("Unable to open \"%s\" for reading\n", _filePath);
exit(-1);
}

unsigned long bufSize = 10000;

_data = (char*)malloc(bufSize);
unsigned int c; unsigned long i = 0;
while( (c = fgetc(fp)) != EOF )
{
if(i == bufSize)
{
bufSize+= 10000;
_data = (char*)realloc(_data, bufSize);
}
_data[i++] = c;
}
fclose(fp);
_dataLen = i;
if(isBinaryFile(filePath))
{
_dataRvmsgType = RVMSG_OPAQUE;
}
}

void
FileService::onRequest(TAWrvRequest* pRequest)
{
pRequest->setHttpReplyHeader("content-type", _contentType);
if(_dataRvmsgType == RVMSG_STRING)
{
pRequest->reply(_data);
}

TIB/Adapter for Web User’s Guide Page 247

C++ Example Service Instances for TIB/Rendevous 5.x

else if(_dataRvmsgType == RVMSG_OPAQUE)

{
pRequest->reply(_data, _dataLen);
}
}

FileService::~FileService()
{
if(_data)free(_data);
}

int main(int argc, char** argv)

{
if(argc < 4)
{
printf("usage: %s <listen subject> <file path> <content-type>\n",
argv[0]);
exit(-1);
}
char* subject = argv[1];
char* filePath = argv[2];
char* contentType = argv[3];

printf("listening on: %s\nreplying with contents of: \"%s\"\nwith

response header \"content-type: %s\"\n", subject, filePath,
contentType);

/* Instantiate FileService and have constructor setup a RvSession. */

FileService fileService((RvSession*)0, subject, filePath, contentType);
if(!fileService.isValid())
{
printf("TAWrvService constructor failed. %s\n",
fileService.getErrorMsg());
return -1;
}
/* Start listening for requests */
if(! fileService.enableRequests() )
printf("Unable to enable request processing: %s\n",
fileService.getErrorMsg());
else
rv_MainLoop(fileService.getRvSession());
return -1;
}

Example Usage
Start the program from the command line. For example, if /foo/bar.gif is a gif image
file, you can run:
> filesvc my.test.filesvc /foo/bar.gif image/gif

Page 248 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

In your browser request:

http://<your web server>/servlet/TAW?subject=my.test.filesvc

The program will return the gif to your browser.

TIB/Adapter for Web User’s Guide Page 249

C++ Example Service Instances for TIB/Rendevous 5.x

worldhello.cc
RV 5.x only
Note the following:

You must derive a subclass from TAWrvService that provides an implementation of

the abstract method onRequest.

The onRequest method is invoked by TAW whenever a request is received. This
implementation returns a greeting in either Japanese, English, or French according to
command line arguments.

Unlike the previous examples, you must provide a properly initialized RvCmqSession
to your constructor.

These four parameter definitions determine how RVDQ decides when to promote a
worker to scheduler. See the TIB/Rendezvous documentation for more details on
these parameters.

Create an instance of WorldHelloService that uses a command line argument to
determine which language translation of hello should be returned.

After instantiating your TAWrvService subclass, you should make sure that it is valid
before proceeding further. The isValid method is used for this purpose.

If the object is not valid, the reason may be determined by invoking the getErrorMsg
method.

Start request processing.

Page 250 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

Code Listing
#include "rv5/TAWrv.h"

#include "rvcmqcpp.h"
#include "rvevm.h"
#include "stdlib.h"
#include "stdio.h"
#include "unistd.h"

#define RVDQ_SCHEDULER_WEIGHT 1
#define RVDQ_SCHEDULER_HEARTBEAT 1000 // milliseconds
#define RVDQ_SCHEDULER_ACTIVATION 3000 // milliseconds
#define RVDQ_LISTEN_SUBJECT "taw.worldhello"
#define RVDQ_SERVICE_POOL "worldhello"

char* greetings[] = { "Hello", "Bon jour", "Konnichiwa", 0 };

#define NUMGREETINGS 3

/* Define an RVDQ-based service */

class WorldHelloService : public TAWrvService
{
public:
WorldHelloService(RvCmqSession *pRvCmqSession, const char*
requestSubject,
int iGreetingNumber);
~WorldHelloService(){};
void onRequest(TAWrvRequest* request);
protected:
int _iGreetingNumber;
};

WorldHelloService::WorldHelloService(RvCmqSession *pRvCmqSession,
const char* requestSubject,
int iGreetingNumber)
: TAWrvService(pRvCmqSession, requestSubject)
{
_iGreetingNumber = iGreetingNumber % NUMGREETINGS;
}

void
WorldHelloService::onRequest(TAWrvRequest* request)
{
char buf[512];
sprintf(buf, "<html><body><h2>%s</body></html>",
greetings[_iGreetingNumber]);
request->setHttpReplyHeader("content-type","text/html");
request->reply(buf);
};

int main(int argc, char** argv)

{
rvevm_Context context;

TIB/Adapter for Web User’s Guide Page 251

C++ Example Service Instances for TIB/Rendevous 5.x

rv_Session s;
if( argc < 2 )
{
printf("usage: %s <language index>\n", argv[0]);
exit(-1);
}
int gNum = atoi(argv[1]);
if( rvevm_Make(&context) != RVEVM_OK)
{
printf("rvevm_Make() failed.\n");
exit(-1);
}
char* rvService = getenv("RVSERVICE");
char* rvNetwork = getenv("RVNETWORK");
char* rvDaemon = getenv("RVDAEMON");
rv_Error err = rv_InitSession(&s, context, rvService, rvNetwork,
rvDaemon);
if(err != RV_OK)
{
printf("rv_InitSession() failed.\n");
exit(-1);
}
RvCmqSession* pRvCmqSession
= new RvCmqSession(s,
RVDQ_SERVICE_POOL,
RVDQ_SCHEDULER_WEIGHT,
RVDQ_SCHEDULER_HEARTBEAT,
RVDQ_SCHEDULER_ACTIVATION );
if(((RvCmqSession*)pRvCmqSession)->status() != RVCM_OK)
{
printf("RvSession constructor failed.\n");
exit(-1);
}
WorldHelloService *pWorldHelloService
= new WorldHelloService(pRvCmqSession, RVDQ_LISTEN_SUBJECT, gNum);
if(!pWorldHelloService->isValid())
{
printf("TAWrvService constructor failed. %s\n",
pWorldHelloService->getErrorMsg());
exit(-1);
}
printf("listening to %s for requests\n", RVDQ_LISTEN_SUBJECT);
if(! pWorldHelloService->enableRequests() )
printf("Unable to enable request processing: %s\n",
pWorldHelloService->getErrorMsg());
else
rv_MainLoop(s);
}

Page 252 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

Example Usage
Start multiple instances of this program from the command line. For example:
> worldhello 0 &
> worldhello 1 &
> worldhello 2 &

This runs three instances in the background. The listen subject, taw.worldhello is
hardcoded into the program. From your browser issue:
http://<your web server>/servlet/TAW?subject=taw.worldhello

Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser.

TIB/Adapter for Web User’s Guide Page 253

C++ Example Service Instances for TIB/Rendevous 5.x

hellogoodbye.cc
RV 5.x only
Note the following:

You must derive a subclass from TAWrvService that provides an implementation of

the abstract method onRequest.

The onRequest method is invoked by TAW whenever a request is received. This
implementation returns a greeting in either Japanese, English, or French according to
command line arguments. It also computes a direct request subject that is used to
prepare a hyperlink that uses this subject to recontact this service instance.

The onDirectRequest method is invoked by TAW whenever a request to the direct
request subject is received. It will return Goodbye in the same language that it used to
return Hello.

You must provide a properly initialized RvCmqSession to your constructor.

These four parameter definitions determine how RVDQ decides when to promote a
worker to scheduler. See the TIB/Rendezvous documentation for more details on
these parameters.

Create an instance of HelloGoodbyeService that uses a command line argument to
determine which language to use for hello and goodbye.

After instantiating your TAWrvService subclass, you should make sure that it is valid
before proceeding further. The isValid method is used for this purpose.

If the object is not valid, the reason may be determined by invoking the getErrorMsg
method.

Start request processing.

Page 254 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

Code Listing
#include "rv5/TAWrv.h"

#include "rvcmqcpp.h"
#include "rvevm.h"
#include "string.h"
#include "stdio.h"
#include "stdlib.h"
#include "unistd.h"

#define RVDQ_SCHEDULER_WEIGHT 1
#define RVDQ_SCHEDULER_HEARTBEAT 1000 // milliseconds
#define RVDQ_SCHEDULER_ACTIVATION 3000 // milliseconds
#define RVDQ_LISTEN_SUBJECT "taw.hellogoodbye"
#define RVDQ_SERVICE_POOL "hellogoodbye"

char* hellos[] = { "Hello", "Bon jour", "Konnichiwa", "Namaste", "Salaam

Malakum", 0 };
char* goodbyes[] = { "Goodbye", "Au revoir", "Sayounara", "Phir Ana", "Ma
Salama", 0 };

#define NUMGREETINGS 5

/* Define an RVDQ-based service */

class HelloGoodbyeService : public TAWrvService
{
public:
HelloGoodbyeService(RvCmqSession *pRvCmqSession, const char*
requestSubject,
int iGreetingNumber);
~HelloGoodbyeService(){};
void onRequest(TAWrvRequest* pRequest);
void onDirectRequest(TAWrvRequest* pRequest);
protected:
int _iGreetingNumber;
};

HelloGoodbyeService::HelloGoodbyeService(RvCmqSession *pRvCmqSession,
const char* requestSubject,
int iGreetingNumber)
: TAWrvService(pRvCmqSession, requestSubject)
{
// Determine which greeting to return
_iGreetingNumber = iGreetingNumber % NUMGREETINGS;
// Compute a direct request subject based on host name and process id
char buf[512];
char nameBuf[256];
strcpy(nameBuf,"unknown");
gethostname(nameBuf, sizeof(nameBuf));
sprintf(buf, "%s.%s.%d", getRequestSubject(), nameBuf, getpid());
setDirectRequestSubject(buf);
}

TIB/Adapter for Web User’s Guide Page 255

C++ Example Service Instances for TIB/Rendevous 5.x

// Handle request forwarded by the RVDQ scheduler

void
HelloGoodbyeService::onRequest(TAWrvRequest* request)
{
/* Return a page containing a greeting and a hyperlink to the
goodbye message in the same language */
char buf[512];
char *subj = new char[::strlen(getDirectRequestSubject())+1];
::strcpy(subj, getDirectRequestSubject());
// return appropriate language greeting and hyperlink containing
// a URL that embeds uses the direct request subject
// if you set up the servlet to process requests at <server>/servlet/TAW
sprintf(buf, "<html><body><h2>%s. <a href=\"/servlet/TAW?subject=%s\">
Now say goodbye. </a></body></html>", hellos[_iGreetingNumber], subj);
delete [] subj;
request->setHttpReplyHeader("content-type","text/html");
request->reply(buf);
};

// Handle direct request from web server

void
HelloGoodbyeService::onDirectRequest(TAWrvRequest* pRequest)
{
char buf[512];
sprintf(buf, "<html><body><h2>%s</body></html>",
goodbyes[_iGreetingNumber]);
pRequest->setHttpReplyHeader("content-type","text/html");
pRequest->reply(buf);
}

int main(int argc, char** argv)

{
rvevm_Context context;
rv_Session s;
if( argc < 2 )
{
printf("usage: %s <language index>\n", argv[0]);
exit(-1);
}
int gNum = atoi(argv[1]);
if( rvevm_Make(&context) != RVEVM_OK)
{
printf("rvevm_Make() failed.\n");
exit(-1);
}
char* rvService = getenv("RVSERVICE");
char* rvNetwork = getenv("RVNETWORK");
char* rvDaemon = getenv("RVDAEMON");
rv_Error err = rv_InitSession(&s, context, rvService, rvNetwork,
rvDaemon);
if(err != RV_OK)
{

Page 256 TIB/Adapter for Web User’s Guide

 Appendix A C++ API Reference for TIB/Rendezvous 5.x

printf("rv_InitSession() failed.\n");
exit(-1);
}
RvCmqSession* pRvCmqSession
= new RvCmqSession(s,
RVDQ_SERVICE_POOL,
RVDQ_SCHEDULER_WEIGHT,
RVDQ_SCHEDULER_HEARTBEAT,
RVDQ_SCHEDULER_ACTIVATION );
if(((RvCmqSession*)pRvCmqSession)->status() != RVCM_OK)
{
printf("RvSession constructor failed.\n");
exit(-1);
}
HelloGoodbyeService *pHelloGoodbyeService
= new HelloGoodbyeService(pRvCmqSession, RVDQ_LISTEN_SUBJECT, gNum);
if(!pHelloGoodbyeService->isValid())
{
printf("TAWrvService constructor failed. %s\n",
pHelloGoodbyeService->getErrorMsg());
exit(-1);
}
printf("listening to %s for requests\n", RVDQ_LISTEN_SUBJECT);
if(! pHelloGoodbyeService->enableRequests() )
printf("Unable to enable request processing: %s\n",
pHelloGoodbyeService->getErrorMsg());
else
rv_MainLoop(s);
}

TIB/Adapter for Web User’s Guide Page 257

C++ Example Service Instances for TIB/Rendevous 5.x

Example Usage
Start multiple instances of this program from the command line. For example:
hellogoodbye 0 &
hellogoodbye 1 &
hellogoodbye 2 &

This runs three instances in the background. The listen subject, taw.hellogoodbye is
hardcoded into the program. From your browser issue:
http://<your web server>/servlet/TAW?subject=taw.hellogoodbye

Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser,
just as you did with worldhello.
Now, if you click “Now say goodbye.”, the URL behind this link causes a request to be
made using the direct request subject. The same service instance that responded with the
greeting will now say goodbye in the same language.

Page 258 TIB/Adapter for Web User’s Guide

Appendix B Java API Reference for
TIB/Rendezvous 5.x

This appendix describes the Java API for TIB/Rendezvous 5.x. Use this API to write
TIB/Adapter for Web service instances when linking to TIB/Rendezvous 5.x. With this
API you can also create a service pool and use TIB/Rendezvous version 5.x distributed
queues to load balance requests to service pool members.

Topics

Overview, page 260

com.tibco.portal.gw.web.api.rv5.TAWrvService, page 261

com.tibco.portal.gw.web.api.rv5.TAWrvRequest, page 276

Java Example Service Instances for TIB/Rendezvous 5.x, page 298

TIB/Adapter for Web User’s Guide Page 259

Overview

Overview

Your TIB/Adapter for Web service instances must perform the following basic steps:
1. Make sure that taweb.jar and rvjpro.jar are in your CLASSPATH.
2. Create a subclass of TAWrvService that implements TAWrvService::onRequest().
Inside onRequest(), arrange for one of the TAWrvRequest::reply() methods to
return data to the servlet.
3. In your subclass main program, instantiate your TAWrvService subclass, and then call
its enableRequests() method to begin listening for requests.
The example programs, simplesvc and filesvc illustrate this basic structure. They also
show how to handle non-text data and manipulate HTTP reply headers. See Java Example
Service Instances for TIB/Rendezvous 5.x on page 298 for details.

Service Pools
In some applications, the request rate can exceed the capacity of a single service instance.
A service pool is a fault-tolerant and load-balanced collection of services.
TIB/Rendezvous Distributed Queues (RVDQ) ensure that a request is delivered to only
one pool member. The TAW Java API makes it very convenient to set up service pools.
For more information on setting up service pools, see Setting up RVDQ Service Pools on
page 324.
There are two classes that you need to know to use the Java API.

com.tibco.portal.gw.web.api.rv5.TAWrvService

com.tibco.portal.gw.web.api.rv5.TAWrvRequest
The interface for these classes are described in this section. Note that you must create your
own subclass of TAWrvService. The onRequest() or onDirectRequest() methods of
this subclass will receive TAWrvRequest objects which contain all of the HTTP
information about the request as well as any data.

Page 260 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

com.tibco.portal.gw.web.api.rv5.TAWrvService
RV 5.x only
Class

Purpose
TAWrvService is an abstract base class that all TAW service instances must subclass. This
subclass must implement the onRequest() method which is invoked whenever a request
is received from TIB/Rendezvous.

Remarks
The constructors provide the ability to:

Create a new standard, non-load-balanced service instance using an RvSession that
will be created for you.

Create a new service instance using an existing TIB/Rendezvous distributed queues
session.

Create a new service instance using an existing reliable TIB/Rendezvous session.
Member Summary

Name Description Page

TAWrvService() Constructor 263

TAWrvService.onRequest() Invoked in response to 265

requests received on the
standard request subject.

TAWrvService.onDirectRequest() Invoked in response to 266

requests received on the
direct request subject.

TAWrvService.setRequestSubject() Set subject associated with 267

onRequest()

TAWrvService.setDirectRequestSubject() Set subject associated with 268

onDirectRequest()

TAWrvService.getDirectRequestSubject() Get the subject is 269

associated with
onDirectRequest()

TIB/Adapter for Web User’s Guide Page 261

com.tibco.portal.gw.web.api.rv5.TAWrvService

Name Description Page

TAWrvService.getRequestSubject() Get the subject is 270

associated with
onRequest()

TAWrvService.enableRequests() Start listening for requests 271

TAWrvService.disableRequests() Stop listening requests 272

TAWrvService.isEnabled() Return true if requests are 273

enabled

TAWrvService.getRvSession() Return the C language API 274

Rendezvous session
encapsulated by the C++
RvSession in use

TAWrvService.getRvCmqSession() Return the C language API 275

Rendezvous session
encapsulated by the C++
RvCmqSession in use

Page 262 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService()
RV 5.x only
Constructor

Declaration
TAWrvService();

TAWrvService(RvSession rvSession) throws RvException;

TAWrvService(RvSession rvSession,
String requestSubject) throws RvException;

TAWrvService(String requestSubject) throws RvException;

TAWrvService(RvCmqSession rvCmqsession) throws RvException;

TAWrvService(RvCmqSession rvCmqsession,
String requestSubject) throws RvException;

TAWrvService(RvCmqSession ,
String requestSubject,
String directRequestSubject) throws RvException;

Purpose
Provide constructors for the TAWrvService class.
TAWrvService() creates a new service instance instance. A reliable TIB/Rendezvous
session is created for use by this instance. The system properties RVSERVICE,
RVNETWORK, and RVDAEMON, may be used to tailor this session. An RvException is
thrown when the TIB/Rendezvous session initialization fails.
TAWrvService(RvSession) creates a new service instance instance using an existing
reliable TIB/Rendezvous session.
TAWrvService(RvSession, String) creates a new service instance instance using an
existing reliable TIB/Rendezvous session, and the specified request subject.
TAWrvService(String) creates a new service instance instance using the specified
request subject. A reliable TIB/Rendezvous session is created for use by this session.
TAWrvService(RvCmqSession) creates a new service instance instance using an existing
TIB/Rendezvous distributed queues session. A reliable TIB/Rendezvous session will be
created for use by this instance.
TAWrvService(RvCmqSession, String) creates a new service instance instance using an
existing TIB/Rendezvous distributed queues session, and the specified request subject.
TAWrvService(RvCmqSession, String, String) create a new service instance instance
using an existing TIB/Rendezvous distributed queues session, and the specified request
and direct request subjects.

TIB/Adapter for Web User’s Guide Page 263

com.tibco.portal.gw.web.api.rv5.TAWrvService

Remarks
All applications must provide a subclass of TAWrvService that implements the
onRequest method.

Subjects need not be specified here, but must be set prior to enabling the service.

Parameters

Name Description

rvCmqSession RVDQ session. You must construct one and provide it to

the constructor.

requestSubject Subject name that the application will be listening for

requests on. All RVDQ-based service pool members listen
to this subject, but RVDQ guarantees delivery to only one
member.

directRequestSubject For RVDQ-based applications, this is a secondary subject

name used to provide direct access to a service pool
member.

rvSession An existing reliable session to embed in the service

instance.

Example
public class SimpleSvc extends TAWrvService
{
public static void main(String argv[])
{
try
{ ...
{
Tibrv.open(Tibrv.IMPL_NATIVE);
SimpleSvc svc = new SimpleSvc();

[truncated...]

Errors
An error will throw an exception:
try { ...
} catch(Exception ...)

Page 264 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService.onRequest()
RV 5.x only
Method

Declaration
public abstract void onRequest(TAWrvRequest request);

Purpose
All applications must provide a subclass of TAWrvService that implements the
onRequest() method. This method is called when a request is received from
TIB/Rendezvous on the primary request subject.

Parameters

Name Description

request TAWrvRequest object that encapsulates all data, HTTP

headers and return address information associated with the
request.

TIB/Adapter for Web User’s Guide Page 265

com.tibco.portal.gw.web.api.rv5.TAWrvService

TAWrvService.onDirectRequest()
RV 5.x only
Method

Declaration
public void onDirectRequest(TAWrvRequest request);

Purpose
This method is only relevant to RVDQ-based service instances. This method is called
when a request is received on the direct request subject. Requests to direct request
subjects are not intercepted by the RVDQ scheduler. The default implementation merely
invokes the onRequest() method.

Parameters

Name Description

request Pointer to the TAWrvRequest object that encapsulates all data,

HTTP header and return address information associated with
the request.

Page 266 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService.setRequestSubject()
RV 5.x only
Method

Declaration
public void setRequestSubject(String subject);

Purpose
This subject is used to specify which subject the service will listen for either normal,
reliable requests, or for RVDQ-based requests. This subject is used by both RVDQ-based
pooled services, or by singleton applications.

Parameters

Name Description

subject Rendezvous subject name that the service will use to listen for
requests.

TIB/Adapter for Web User’s Guide Page 267

com.tibco.portal.gw.web.api.rv5.TAWrvService

TAWrvService.setDirectRequestSubject()
RV 5.x only
Method

Declaration
public void setDirectRequestSubject(String subject);

Purpose
Set the subject name used to listen for requests directed at a specific member of an
RVDQ-based service pool. This subject is not used by RvSession-based services at all.
RVDQ-based applications can use this subject to get requests without the intervention of
the RVDQ scheduler.

Parameters

Name Description

subject Rendezvous subject name that the service will use to listen for
direct requests.

Page 268 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService.getDirectRequestSubject()
RV 5.x only
Method

Declaration
public String getDirectRequestSubject();

Purpose
Get the subject name used to listen for requests directed at a specific member of an
RVDQ-based service pool. This subject is not used by RvSession-based services at all.
RVDQ-based applications can use this subject to get requests without the intervention of
the RVDQ scheduler. This is a secondary subject used by RVDQ-based services to listen
for requests that bypass RVDQ load-balancing.

Parameters
Returns a pointer to the subject name string or NULL.

TIB/Adapter for Web User’s Guide Page 269

com.tibco.portal.gw.web.api.rv5.TAWrvService

TAWrvService.getRequestSubject()
RV 5.x only
Method

Declaration
public String getRequestSubject();

Purpose
Get the primary subject name used to listen for requests. This subject is used by both
RVDQ-based pooled services, or by singleton applications.

Parameters
Returns the subject used for reliable or RVDQ-based requests.

Page 270 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService.enableRequests()
RV 5.x only
Method

Declaration
public void enableRequests() throws TAWException;

Purpose
Before the service will start receiving requests through its onRequest method, the
enableRequests method must be invoked. This sets up the necessary TIB/Rendezvous
listeners.

Parameters
None.

Remarks
Prior to invoking enableRequest(), you must have set the subjects that your service will
accept requests on. You can do this in the constructor, or use setRequestSubject() and
setDirectRequestSubject(). This method creates RvListeners that remain valid until
the disableRequests() method is invoked.
Note that an exception is thrown when either no requestSubject has been set, or if a
TIB/Rendezvous listener cannot be created.

TIB/Adapter for Web User’s Guide Page 271

com.tibco.portal.gw.web.api.rv5.TAWrvService

TAWrvService.disableRequests()
RV 5.x only
Method

Declaration
public void disableRequests();

Purpose
This method allows the service to suspend request processing. This method causes the
service to stop listening for requests.

Remarks
This method destroys the RvListeners created in enableRequests().

Parameters
None.

Page 272 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService.isEnabled()
RV 5.x only
Method

Declaration
public boolean isEnabled();

Purpose
Whether the service is currently listening for requests may be determined by using this
method.

Parameters
Returns RV_TRUE if the service is currently listening for requests, RV_FALSE otherwise.

TIB/Adapter for Web User’s Guide Page 273

com.tibco.portal.gw.web.api.rv5.TAWrvService

TAWrvService.getRvSession()
RV 5.x only
Method

Declaration
public RvSession getRvSession();

Purpose
Get the reliable TIB/Rendezvous session handle in use.

Parameters
Returns the RvSession object in use.

Page 274 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvService.getRvCmqSession()
RV 5.x only
Method

Declaration
public RvSession getRvCmqSession();

Purpose
Get the RVDQ TIB/Rendezvous session handle in use.

Parameters
Returns the RvCmqSession object in use.

TIB/Adapter for Web User’s Guide Page 275

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

com.tibco.portal.gw.web.api.rv5.TAWrvRequest
RV 5.x only
Class

Purpose
TAWrvRequest objects are manufactured by the TIB/Adapter for Web API when requests
are received. This class encapsulates an HTTP request from the time it is delivered to your
service instance, to after your reply has been transmitted. Its interface consists primarily
of accessors for HTTP protocol information, including the data payload. The reply
method is used to send data back to the browser or other HTTP client.
These objects are created and destroyed by TAW, and are made available to you through
the TAWrvService member callback functions onRequest and onDirectRequest.

Member Summary

Name Description Page

TAWrvRequest.getReplySubjec Returns the subject that the servlet is 278

t()
using to listen for the reply.

TAWrvRequest.getUrlPath() Extract the path component from the 279

URL in the HTTP request line.

TAWrvRequest.getUrlResource Extract the name of the resource from the 280

()
URL in the HTTP request line.

TAWrvRequest.getHttpMethod( Return the HTTP method from the HTTP 281

)
request line.

TAWrvRequest.getHttpUri() Return the HTTP URI from the HTTP 282

request line.

TAWrvRequest.getHttpVersion Return the HTTP version from the HTTP 283

()
request line.

TAWrvRequest.getHttpRequest Get the HTTP entity body (i.e. POST 284

EntityBody()
data) from the request.

TAWrvRequest.getUrlParamete Lookup the value of a URL query 285

r()
parameter by name.

Page 276 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

Name Description Page

TAWrvRequest.getUrlParamete Return all URL query parameters. 286

rs()

TAWrvRequest.getHttpRequest Lookup the value of a specified HTTP 287

Header()
request header.

TAWrvRequest.getHttpRequest Get all HTTP request headers. 288

Headers()

TAWrvRequest.setHttpReplyEn Determine the reply payload data. 289

tityBody()

TAWrvRequest.setHttpReplyHe Add a header to the reply. 290

ader()

TAWrvRequest.setHttpStatusC Set the reply status code in the HTTP 291

ode()
status line.

TAWrvRequest.getRvdqSenderN Get the RVDQ sender name from the 292

ame()
request.

TAWrvRequest.getRvdqSequenc Get the RVDQ sequence number from the 293

eNumber()
request.

TAWrvRequest.reply() Marshall reply and send to servlet. 294

TAWrvRequest.getProtocolVer Get the TIB/Adapter for Web protocol 296

sion()
version.

TAWrvRequest.setHttpReasonP Set the reply reason phrase the HTTP 297

hrase()
status line.

TIB/Adapter for Web User’s Guide Page 277

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getReplySubject()
RV 5.x only
Method

Declaration
public String getReplySubject();

Purpose
This method returns the subject that the TIB/Adapter for Web servlet is using to listen for
the reply.

Parameters
Returns the subject name string.

Page 278 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.getUrlPath()
RV 5.x only
Method

Declaration
public String getUrlPath() throws TAWException;

Purpose
Get the path from the URL in the HTTP request line. For example, if the URL is
//foo/bar/baz.htm, the path is //foo/bar.

Parameters
Returns the path string.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

TIB/Adapter for Web User’s Guide Page 279

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getUrlResource()
RV 5.x only
Method

Declaration
public String getUrlResource() throws TAWException;

Purpose
Get the target resource string from the URL in the HTTP request line. For example, if the
URL is //foo/bar/baz.htm, the resource is baz.htm.

Parameters
Returns the resource string.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

Page 280 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.getHttpMethod()
RV 5.x only
Method

Declaration
public String getHttpMethod() throws TAWException;

Purpose
Get the HTTP method from the request line.

Parameters
Returns the HTTP method string.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

TIB/Adapter for Web User’s Guide Page 281

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getHttpUri()
RV 5.x only
Method

Declaration
public String getHttpUri() throws TAWException;

Purpose
Get the HTTP URI from the request line. For example /foo/bar/baz.htm

Parameters
Returns the HTTP URI string.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

Page 282 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.getHttpVersion()
RV 5.x only
Method

Declaration
public String getHttpVersion() throws TAWException;

Purpose
Get the HTTP version string from the request line. For example: HTTP/1.0

Parameters
Returns the HTTP version string.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

TIB/Adapter for Web User’s Guide Page 283

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getHttpRequestEntityBody()
RV 5.x only
Method

Declaration
public String getHttpRequestEntityBody() throws TAWException;

Purpose
Get the HTTP entity body (i.e. POST data) from the request.

Parameters
Returns the HTTP data string.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

Page 284 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.getUrlParameter()
RV 5.x only
Method

Declaration
public String getUrlParameter(String name) throws TAWException;

Purpose
Gets the value of an individual query parameter from the URL on the request line. The
lookup is case sensitive.

Parameters

Name Description

name Name of the query parameter specified on the URL request

line.

Returns a string holding the value associated with parameter name or NULL.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

TIB/Adapter for Web User’s Guide Page 285

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getUrlParameters()
RV 5.x only
Method

Declaration
public RvMsg getUrlParameters() throws TAWException;

Purpose
This method gets all query parameters from the URL on the request line.

Parameters
Returns an RvMsg containing one field for each parameter or NULL.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

Page 286 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.getHttpRequestHeader()
RV 5.x only
Method

Declaration
public String getHttpRequestHeader(String name) throws TAWException;

Purpose
Gets the value of a request header by name. The lookup is case insensitive.

Parameters

Name Description

name Name of the header.

Returns a string holding the header value associated with header name or NULL.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

TIB/Adapter for Web User’s Guide Page 287

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getHttpRequestHeaders()
RV 5.x only
Method

Declaration
public RvMsg getHttpRequestHeaders() throws TAWException;

Purpose
Gets all of the HTTP request headers.

Parameters
Returns an RvMsg containing one field for each header or NULL.

Remarks
An exception is thrown when the value of the corresponding RvMsg field is not a string.

Page 288 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.setHttpReplyEntityBody()
RV 5.x only
Method

Declaration
public void setHttpReplyEntityBody(String body);
public void setHttpReplyEntityBody(byte body[]);

Purpose
Set the HTTP reply entity body. This is how you associate reply data with the request. The
first form is used to specify the reply as a string. The second form is used to return binary
data such as images.

Parameters

Name Description

body A null-terminated string.

body[] A buffer of binary data.

TIB/Adapter for Web User’s Guide Page 289

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.setHttpReplyHeader()
RV 5.x only
Method

Declaration
public void setHttpReplyHeader(String name, String value);
public void setHttpReplyHeader(String name, int value);

Purpose
Set a HTTP reply header to either a string or an integer. Any pre-existing value for that
header is replaced.

Parameters

Name Description

name Header name.

value Header string or integer value.

Page 290 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.setHttpStatusCode()
RV 5.x only
Method

Declaration
public void setHttpStatusCode(int code);

Purpose
Set an HTTP reply status code.

Parameters

Name Description

code HTTP reply status code.

TIB/Adapter for Web User’s Guide Page 291

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getRvdqSenderName()
RV 5.x only
Method

Declaration
public String getRvdqSenderName();

Purpose
Get the name of the RVDQ sender. This is only relevant to RVDQ-based service instances.

Parameters
Returns the string holding the RVDQ sender name.

Page 292 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.getRvdqSequenceNumber()
RV 5.x only
Method

Declaration
public int getRvdqSequenceNumber();

Purpose
Get the RVDQ sequence number of this request message. This is only relevant to
RVDQ-based service instances.

Parameters
Returns the sequence number.

TIB/Adapter for Web User’s Guide Page 293

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.reply()
RV 5.x only
Method

Declaration
public void reply() throws TAWException

public void reply(byte entityBody[]) throws TAWException;

public void reply(byte entityBody[],

int statusCode) throws TAWException;

public void reply(byte entityBody[],

int statusCode,
String reasonPhrase) throws TAWException;

public void reply(String entityBody) throws TAWException;

public void reply(String entityBody,

int statusCode) throws TAWException

public void reply(String entityBody,

int statusCode,
String reasonPhrase) throws TAWException

Purpose
These methods are used to send a reply back to the HTTP client through the web browser.
The simplest form reply() is used to send a reply back to the HTTP client through the
web browser when all HTTP reply information, including reply data, status code, and
reason phrase have already been set via TAWrvRequest accessor methods. If no status
code or reason phrase has been set, “200” and “OK” respectively will be used.
The remaining forms are for convenience, and allow you to set string or binary data,
status code, and reason phrase in one call.
reply(byte entityBody[]) sends a reply containing binary data back to the HTTP
client through the web browser.
reply(byte entityBody[], int statusCode) sends a reply containing binary data
and an HTTP status code back to the HTTP client through the web browser.
reply(byte entityBody[], int statusCode, string reasonPhrase) sends a reply
containing binary data, an HTTP status code, and reason phrase back to the HTTP client
through the web browser.
reply(String entityBody) sends a reply containing string data back to the HTTP
client through the web browser.

Page 294 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

reply(String entityBody, int statusCode) sends a reply containing string data and
an HTTP status code back to the HTTP client through the web browser.
reply(String entityBody[], int statusCode, String reasonPhrase) sends a
reply containing string data, an HTTP status code, and reason phrase back to the HTTP
client through the web browser.

Parameters

Name Description

entityBody The reply string or binary data.

statusCode HTTP status code.

reasonPhase HTTP reason phrase.

Remarks
An TAWException is thrown when there is a TIB/Rendezvous error during the
transmission of the reply.

TIB/Adapter for Web User’s Guide Page 295

com.tibco.portal.gw.web.api.rv5.TAWrvRequest

TAWrvRequest.getProtocolVersion()
RV 5.x only
Method

Declaration
public int getProtocolVersion();

Purpose
Get the TIB/Adapter for Web version number.

Parameters
Returns the TIB/Adapter for Web version number.

Page 296 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

TAWrvRequest.setHttpReasonPhrase()
RV 5.x only
Method

Declaration
public void setHttpReasonPhrase(String phrase);

Purpose
This method sets the reply HTTP reason phrase that should accompany the status code.
For example, OK.

Parameters

Name Description

phrase descriptive phrase that accompanies the HTTP reply status code.

TIB/Adapter for Web User’s Guide Page 297

Java Example Service Instances for TIB/Rendezvous 5.x

Java Example Service Instances for TIB/Rendezvous 5.x

Four example Java programs are provided with TIB/Adapter for Web.

SimpleSvc. This is a glorified "Hello World!" program that allows you to specify the
subject the service will listen for requests on, and the string it will return.
FileSvc. This shows how to transmit string or binary data and set HTTP reply headers.
WorldHello. This is a service pool example. Depending on the command line argument
given, the service will return a language-specific greeting. If you run multiple instances of
this service, each replying in a different language, requests will be randomly distributed
to worker services by the RVDQ scheduler, and you will see greetings in different
languages if you make multiple requests.
HelloGoodbye. This is another service pool example. This shows how an initial request
can be directed to a worker service by the RVDQ scheduler, and how the direct request
subject is used to bypass the RVDQ scheduler for subsequent requests from the same
client. In addition to returning a language-specific greeting like worldhello, this service
also returns a hyperlink that contains the direct request subject. When this hyperlink is
clicked on, the client communicates directly with the service instance instance that
provide the greeting page.

Compiling the Service Examples

You must create the service example executables:
1. cd <install_path>/samples/rv5/java

2. Edit the Makefile to reflect your environment.

3. Type make.
4. This will make the executables for all the following examples.

Page 298 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

SimpleSvc
RV 5.x only
Note the following:

All service instances must subclass TAWrvService and implement the abstract request
callback member function onRequest.

A TAWrvRequest object is created by TAW when a request is received and is delivered
to an application through the onRequest method. The reply member of TAWrvRequest
is used to transmit the reply string to the client.

In main, a SimpleSvc instance is first created. Then its request subject, and the string
to provide in the reply are set. Finally, requests are enabled.

TAWrvRequest object contain an invisible “return address” that is used by the reply
method to return data to the client through the servlet.

Code Listing
import com.tibco.portal.gw.web.api.rv5.*;
import COM.TIBCO.rv.*;

public class SimpleSvc extends TAWrvService

{
public static void main(String argv[])
{
try
{
if(argv.length != 2)
System.out.println("usage: java SimpleSvc <listen subject> <reply
string>");
else
{
SimpleSvc svc = new SimpleSvc();
svc.setRequestSubject(argv[0]);
svc.replyString = argv[1];
svc.enableRequests();
System.out.println("Listening on: " + argv[0]);
System.out.println("Replying with: " + argv[1]);
}
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

public SimpleSvc() throws RvException { super(); }

public void onRequest(TAWrvRequest request)

TIB/Adapter for Web User’s Guide Page 299

Java Example Service Instances for TIB/Rendezvous 5.x

{
try
{
request.reply(replyString);
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

private String replyString;

}

Example Usage
Start the program from the command line. For example:
java SimpleSvc my.test.simplesvc hello

In your browser, request

http://<your web server>/servlet/TAW?subject=my.test.simplesvc

The program will return a page containing "hello" to your browser.

Page 300 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

FileSvc
RV 5.x only
Note the following:

All service instances must subclass TAWrvService and implement the abstract request
callback member function onRequest.

A TAWrvRequest object is created by TAW when a request is received and is delivered
to an application through the onRequest method. The reply member of TAWrvRequest
is used to transmit the reply string to the client. An HTTP “content-type” reply
header is set from the command-line-specified value which should be chosen to reflect
the type of file. Next, the appropriate form of reply is used to transmit the file contents
back to the client.

In main, a SimpleSvc instance is created. The desired request subject and content type
are set from command line parameters. The specified file is loaded into a buffer, and if
it is either a .gif or .jpg file, the file is considered a binary file. Finally, requests are
enabled.

When a request is received, the contents of the file are returned to the client using the
appropriate form of reply() for the type of file.

Code Listing
import java.io.*;
import com.tibco.portal.gw.web.api.rv5.*;
import COM.TIBCO.rv.*;

public class FileSvc extends TAWrvService

{
private static final String usageString
= "usage: java FileSvc <listen subject> <file path> <content-type>";
public static void main(String argv[])
{
try
{
if(argv.length != 3)
System.out.println(usageString);
else
{
// Create and initialize service
FileSvc svc = new FileSvc();
svc.setRequestSubject(argv[0]);
svc.contentType = argv[2];
System.out.println("Listening on: " + argv[0]);
System.out.println("Replying with contents of: " + argv[1]);
System.out.println("with reply header: \"content-type: "
+ svc.contentType + "\"");
// Read file into buffer

TIB/Adapter for Web User’s Guide Page 301

Java Example Service Instances for TIB/Rendezvous 5.x

FileInputStream fis = new FileInputStream(argv[1]);

int bufsize = 10000;
svc.bytes = new byte[bufsize];
for( svc.bytesRead = fis.read(svc.bytes);
svc.bytesRead == svc.bytes.length ;
svc.bytesRead = fis.read(svc.bytes))
{
bufsize *= 2;
svc.bytes = new byte[bufsize];
fis.close();
fis = new FileInputStream(argv[1]);
}
// Check for known types of binary files
svc.isBinaryFile =
( argv[1].endsWith(".gif") || argv[1].endsWith(".jpg") ) ?
true : false;
// Start processing requests
svc.enableRequests();
}
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

public FileSvc() throws RvException { super(); }

public void onRequest(TAWrvRequest request)

{
try
{
request.setHttpReplyHeader("content-type", contentType);
if(isBinaryFile)
request.reply(bytes);
else
request.reply(new String(bytes, 0, bytesRead));
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}
private int bytesRead;
private byte[] bytes;
private String contentType;
private boolean isBinaryFile;
}

Page 302 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

Example Usage
Start the program from the command line. For example: if /foo/bar.gif is a gif image
file, you can run:
> java FileSvc my.test.filesvc /foo/bar.gif image/gif

In your browser, request:

http://<your web server>/servlet/TAW?subject=my.test.filesvc

The program will return the gif to your browser.

TIB/Adapter for Web User’s Guide Page 303

Java Example Service Instances for TIB/Rendezvous 5.x

WorldHello
RV 5.x only
Note the following:

All service instances must subclass TAWrvService and implement the abstract request
callback member function onRequest.

There are no TAWrvService constructors that will build a RVDQ session for you, so
you must build one yourself.

These parameters are used to control the service pools fault-tolerant behavior, as well
as specify the request subject.

Create an instance of WorldHello using the RVDQ session just created. Setup reply
data hash table and finally enable requests.

When a request is received, the onRequest method looks up the appropriate greeting
in the hash table and invokes request's reply method to send it back to the client.

Code Listing
import java.util.*;
import com.tibco.portal.gw.web.api.rv5.*;
import COM.TIBCO.rv.*;

public class WorldHello extends TAWrvService

{
private static final int rvdqSchedulerWeight = 1;
private static final int rvdqSchedulerHeartbeat = 1000; // milliseconds
private static final int rvdqSchedulerActivation = 3000; // milliseconds
private static final String rvdqListenSubject = "taw.worldhello";
private static final String rvdqServicePool = "WorldHello";

public static void main(String argv[])

{
try
{
if(argv.length != 1)
{
System.out.println("usage: java WorldHello <language>");
System.out.println("language = english, french, or japanese");
}
else
{
RvCmqSession session
= new RvCmqSession(System.getProperty("RVSERVICE"),
System.getProperty("RVNETWORK"),
System.getProperty("RVDAEMON"),
rvdqServicePool,
rvdqSchedulerWeight,

Page 304 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

rvdqSchedulerHeartbeat,
rvdqSchedulerActivation);

WorldHello svc
= new WorldHello(session, rvdqListenSubject);
svc.language = argv[0];
svc.greetings = new Hashtable();
svc.greetings.put("english", "Hello");
svc.greetings.put("french", "Bon jour");
svc.greetings.put("japanese", "Konnichiwa");
svc.enableRequests();
System.out.println("Listening on: "+rvdqListenSubject);
}
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

public WorldHello(RvCmqSession s, String subj) throws RvException {

super(s, subj); }

public void onRequest(TAWrvRequest request)

{
try
{
String greeting = (String)this.greetings.get(this.language);
request.setHttpReplyHeader("content-type","text/plain");
if(greeting != null)
request.reply(greeting);
else
request.reply("No greeting for language " + this.language);
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

private String language;

private Hashtable greetings;
}

TIB/Adapter for Web User’s Guide Page 305

Java Example Service Instances for TIB/Rendezvous 5.x

Example Usage
Start multiple instances of this program from the command line. For example:

> java WorldHello english &

> java WorldHello french &
> java WorldHello japanese &

This runs three instances in the background. The listen subject, taw.worldhello is
hardcoded into the program. From your browser issue:
http://<your web server>/servlet/TAW?subject=taw.WorldHello

Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser.

Page 306 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

HelloGoodbye
RV 5.x only
Note the following:

All service instances must subclass TAWrvService and implement the abstract
request callback member function onRequest.

There are no TAWrvService constructors that will build a RVDQ session for you, so
you must build one yourself.

These parameters are used to control the service pools fault-tolerant behavior, as well
as specify the request subject.

Create an instance of WorldHello using the RVDQ session just created.

Construct a unique direct request subject by concatenating the identifier specified on
the command line with the request subject and provide it to the service instance. Setup
the reply hash tables and finally enable requests.

Initial requests from a client are delivered to the service through the onRequest
method. This method builds an HTML page that consists of a hyperlink that displays
as hello or foreign language equivalent. The URL in this link embeds the direct
request subject so that when the link is followed, a request will be sent to the service's
direct request subject. This page is then returned to the client.

The onDirectRequest method will never be invoked on the initial client request. It is
only invoked after the service has returned the hello page described above, and after
the user has clicked on the link. In response, the same language that was used to say
hello will be used to prepare a goodbye page.

Code Listing
import java.util.*;
import com.tibco.portal.gw.web.api.rv5.*;
import COM.TIBCO.rv.*;

public class HelloGoodbye extends TAWrvService

{
private static final int rvdqSchedulerWeight = 1;
private static final int rvdqSchedulerHeartbeat = 1000; // milliseconds
private static final int rvdqSchedulerActivation = 3000; // milliseconds
private static final String rvdqListenSubject = "taw.hellogoodbye";
private static final String rvdqServicePool = "HelloGoodbye";

public static void main(String argv[])

{
try
{

TIB/Adapter for Web User’s Guide Page 307

Java Example Service Instances for TIB/Rendezvous 5.x

if(argv.length != 2)
{
System.out.println("usage: java HelloGoodbye <language> <unique
id>");
System.out.println("language = english, french, or japanese");
}
else
{
RvCmqSession session
= new RvCmqSession(System.getProperty("RVSERVICE"),
System.getProperty("RVNETWORK"),
System.getProperty("RVDAEMON"),
rvdqServicePool,
rvdqSchedulerWeight,
rvdqSchedulerHeartbeat,
rvdqSchedulerActivation);

HelloGoodbye svc
= new HelloGoodbye(session, rvdqListenSubject);
// Concatenate unique id to request subject to form the direct
// request subject
String s = rvdqListenSubject + "." + argv[1];
svc.setDirectRequestSubject(s);
svc.language = argv[0];
svc.hellos = new Hashtable();
svc.hellos.put("english", "Hello");
svc.hellos.put("french", "Bon jour");
svc.hellos.put("japanese", "Konnichiwa");
svc.goodbyes = new Hashtable();
svc.goodbyes.put("english", "Goodbye");
svc.goodbyes.put("french", "Au revoir");
svc.goodbyes.put("japanese", "Sayonara");
svc.enableRequests();
System.out.println("Listening on: "+rvdqListenSubject);
}
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

public HelloGoodbye(RvCmqSession s, String subj) throws RvException {

super(s, subj); }

public void onDirectRequest(TAWrvRequest request)

{
try
{
request.setHttpReplyHeader("content-type","text/html");
request.reply("<html><body><h2>" + (String)goodbyes.get(language)
+ "</body></html>");
}

Page 308 TIB/Adapter for Web User’s Guide

 Appendix B Java API Reference for TIB/Rendezvous 5.x

catch(Exception e)
{
System.out.println(e.getMessage());
}
}

public void onRequest(TAWrvRequest request)

{
try
{
String hello = (String)this.hellos.get(this.language);
if(hello != null)
{
String url = getDirectRequestSubject();
String s = "<html><body><a href=/servlet/TAW?subject=" + url + ">"
+ hello + "</a></body></html>";
request.setHttpReplyHeader("content-type","text/html");
request.reply(s);
}
else
request.reply("No hello for language " + this.language);
}
catch(Exception e)
{
System.out.println(e.getMessage());
}
}

private String language;

private Hashtable hellos;
private Hashtable goodbyes;
}

TIB/Adapter for Web User’s Guide Page 309

Java Example Service Instances for TIB/Rendezvous 5.x

Example Usage
Start multiple instances of this program from the command line. For example:
> java hellogoodbye english 0 &
> java hellogoodbye french 1 &
> java hellogoodbye japanese 2 &

This runs three instances in the background. The listen subject, taw.hellogoodbye is
hardcoded into the program. From your browser issue:
http://<your web server>/servlet/TAW?subject=taw.hellogoodbye

Each time you do so, you will see either Hello, Bonjour or Konnichiwa in your browser,
depending upon which service handles your request.
If you now click on this link, a request will be sent back to the same service using its direct
request subject. The service will respond with goodbye in the same language it used
before. The last numeric argument is used to make a unique direct request subject.

Page 310 TIB/Adapter for Web User’s Guide

Appendix C TIB/Rendezvous 6.x Facilities

TIB/Rendezvous messages are exchanged between the TIB/Adapter for Web servlet and
your external service instance to complete each client request. This appendix describes
how the TibrvMsg exchange works, and gives the detailed request and reply message
formats. You can use this information to write service instances on platforms that are
supported by TIB/Rendezvous, but do not yet have a corresponding TAW API.
This section also explains how to use the TAW API for TIB/Rendezvous 6.x to set up
RVDQ service pools, and how the API supports client/pool member sessions.

Topics

Protocol, page 312

Request and Reply TibrvMsg Formats, page 313

RVDQ Service Pools, page 316

TIB/Adapter for Web User’s Guide Page 311

Protocol

Protocol

Request and reply messages (TibrvMsgs) are exchanged between the TIB/Adapter for
Web servlet and an external service instance to complete each client request. Both request
and reply messages conform to the AE 3.0 wire format.
The actual data content or payload of the HTTP message is carried by the ^data^ wire
format field. HTTP headers, request-line, and status-line are all parsed into appropriate
TibRvMsgs fields. Applications that cannot, or do not wish to use the TIB/Adapter for
Web API, may provide their own custom code to marshall and unmarshall these fields
and transmit the reply message to the TIB/Adapter for Web servlet.
The return address of the servlet that sent the request is not a field in either the request or
reply message. The servlet uses TibrvTransport::sendRequest() to send the request to
your service instance and create an inbox listener to receive your reply. When you receive
a request, your TibrvMsgCallback::onMsg() method is called and given an
TibrvTransport to use to send the reply.

Applications that are AE 3.0 wire format aware, and have no need to inspect or
manipulate HTTP protocol information, need only concern themselves with the
^-delimited AE 3.0 wire format fields. POST data will appear in the request msg ^data^
field, and the ^data^ field of the reply message carries the reply data payload.

Page 312 TIB/Adapter for Web User’s Guide

 Appendix C TIB/Rendezvous 6.x Facilities

Request and Reply TibrvMsg Formats

In the following tables, the com.tibco.portal.gw.web.TAWrvMsgFLD column provides

the class member constants in Java. Refer to the RawSvc.java sample on page 196 for an
example of how to use it without the API. For C++. Use the constants in TAWrvMsg.h
found in the include directory and program accordingly using the TIB/Rendezvous API.

Table 1 TibrvMsg fields common to both request and reply messages

TAWrvMsgFLD TibrvMsg field Rv Type Description

PFMT ^pfmt^ TIBRVMSG_I16 For pre AE 3.0 wire format

compatibility. Constant value 10.
VER ^ver^ TIBRVMSG_I16 Wire format version. 30 for AE 3.0
TYPE ^type^ TIBRVMSG_I16 Wire Format ^data^ type 10 (string)
or 1 (RvMsg)

Table 2 Request message TibrvMsg fields

TAWrvMsgFLD TibrvMsg field Rv type Description

DATA ^data^ TIBRVMSG_STRING Request data from the HTTP client.

HTTP_METHOD HTTPmethod TIBRVMSG_STRING From HTTP request-line: GET or
POST
HTTP_URI HTTPuri TIBRVMSG_STRING From HTTP request-line. For
example: /foo/bar.tibrv
HTTP_VERSION HTTPversion TIBRVMSG_STRING From HTTP request-line. For
example: HTTP/1.0
HTTP_HEADERS HTTPheaders TIBRVMSG_RVMSG Name/value pairs corresponding
to HTTP general, request, or entity
headers.

TIB/Adapter for Web User’s Guide Page 313

Request and Reply TibrvMsg Formats

Table 2 Request message TibrvMsg fields

TAWrvMsgFLD TibrvMsg field Rv type Description

URL_PATH URLpath TIBRVMSG_STRING From HTTP request-line. For

example: given the URI
//foo/bar/baz.html, URLpath is
//foo/bar.

URL_RESOURCE URLresource TIBRVMSG_STRING From HTTP request-line. For

example: given the URI
//foo/bar/baz.html,
URLresource is baz.html.
URL_PARAMETE URLparameter TIBRVMSG_MSG From HTTP request-line. For
RS s
example: given the URI
//foo/bar/baz.tibrv?p1=v1&p2
=v2, URLparameters will be an
RvMsg containing fields p1, and
p2, with corresponding values v1,
and v2.
VERSION_CODE TAWversion TIBRVMSG_I32 Inserted by API to assist
interoperation between TAW
versions.

Page 314 TIB/Adapter for Web User’s Guide

 Appendix C TIB/Rendezvous 6.x Facilities

Table 3 Reply TibrvMsg fields

TAWrvMsgFLD TibrvMsg field Rv type Description

DATA ^data^ TIBRVMSG_STRING Response data from the service

instance. Most web clients will require
that the mime type be specified in a
Content-Type header in HTTP headers
field of this message.
HTTP_STATUS_ HTTPstatusCo TIBRVMSG_I32 HTTP status code. For example: 200
CODE de

HTTP_REASON_ HTTPreasonPh TIBRVMSG_STRING Message associated with

PHRASE rase
HTTPstatusCode. For example, OK is
typical for 200.
HTTP_HEADERS HTTPheaders TIBRVMSG_MSG Name/value pairs corresponding to
response headers.
VERSION_CODE TAWversion TIBRVMSG_I32 Inserted by API to assist interoperation
between TIB/Adapter for Web
versions.
HTTP_CONTENT HTTPcontentT TIBRVMSG_STRING HTTP content type, inserted by the API
_TYPE ype
so that the servlet can set the content
type directly.

TIB/Adapter for Web User’s Guide Page 315

RVDQ Service Pools

RVDQ Service Pools

In some applications the message traffic can exceed the capacity of a single service
instance. A service pool can handle a large amount of message traffic. A service pool is a
collection of running applications that use Rendezvous Distributed Queues for
load-balancing requests and fault-tolerance.
Each server application in the pool listens to the same request subject, and
TIB/Rendezvous ensures that only one server receives any particular request. At any
point in time, one of the servers in the pool is the scheduler, and the others are workers.
RVDQ takes care of promoting a worker to a scheduler should the scheduler crash or
otherwise become non-responsive. When a request is issued, the scheduler determines
which server to forward the request to based upon RVDQ tuning parameters, as
described in TIB/Rendezvous documentation.

Setting up RVDQ Service Pools

While you can use the RVDQ API methods directly to set up a service pool, both the C++
and Java APIs that are provided with TIB/Adapter for Web make it easier for you to do
so. The APIs also make it possible for the initial client request to be directed to a service
pool member, according to load-balancing considerations, and for succeeding client
requests to bypass the RVDQ scheduler to maintain a session with the same pool member.
To create a service pool you follow the same basic steps as when you are setting up a
single queue processor, but when you instantiate the TAWrvService subclass that you
have defined, you provide it with a TibrvCmQueueTransport that is used to participate in
the service pool. For more information about service pools and RVDQ-based load
balancing, please refer to the TIB/Rendezvous distributed queue documentation. The
worldhello example program illustrate the use of a service pool using RVDQ. The C++
version is annotated on page 112. The Java version is annotated on page 185.

Page 316 TIB/Adapter for Web User’s Guide

 Appendix C TIB/Rendezvous 6.x Facilities

Creating Sessions within RVDQ Service Pools

When a client initially makes a request, one application in the service pool, acting as the
RVDQ scheduler, forwards the request to a worker instance, which invokes your service’s
onMsg() method to process the request. The initial request is made to a request subject, just
as it would be for a non-RVDQ service. Part of the reply includes the worker’s direct
request subject, which allows the client to make requests directly to this worker in future,
without any intervention by the RVDQ scheduler. When a worker has specified a direct
request subject to a client, it will also be listening for requests on that subject from then on.
The TIB/Adapter for Web APIs support the notion of the direct request subject as an
additional subject that is unique to each worker instance. The direct request subject is
typically used when worker applications need to maintain state on the behalf of
individual clients. The client doesn't care which worker is initially assigned to its request,
but does require that follow-up requests be directed to the same worker.
For example, suppose each member of your pool is designed to present data to a client on
a page-at-a-time basis. The requesting client doesn't care which worker handles its initial
request, but it does need to get back to the same worker if it wants the next or previous
page. In this scenario, the worker's reply to the initial request will include the direct
request subject. The client uses this subject to make subsequent requests to the same
worker, who is keeping track of what page it last sent to the client.
The example program hellogoodbye shows how this works. The C++ version is
annotated on page 116. The Java version is annotated on page 187.

TIB/Adapter for Web User’s Guide Page 317

RVDQ Service Pools

Page 318 TIB/Adapter for Web User’s Guide

Appendix D TIB/Rendezvous 5.x Facilities

TIB/Rendezvous messages are exchanged between the TIB/Adapter for Web servlet and
your external service instance to complete each client request. This appendix describes
how the RvMsg exchange works, and gives the detailed request and reply message
formats. You can use this information to write service instances on platforms that are
supported by TIB/Rendezvous, but do not yet have a corresponding TAW API.
This section also explains how to use the TAW API for TIB/Rendezvous 5.x to set up
RVDQ service pools, and how the API supports client/pool member sessions.

Topics

Protocol, page 320

Request and Reply RvMsg Formats, page 321

RVDQ Service Pools, page 324

TIB/Adapter for Web User’s Guide Page 319

Protocol

Protocol

Request and reply messages (RvMsgs) are exchanged between the TIB/Adapter for Web
servlet and an external service instance to complete each client request. Both request and
reply messages conform to the AE 3.0 wire format.
The actual data content or payload of the HTTP message is carried by the ^data^ wire
format field. HTTP headers, request-line, and status-line are all parsed into appropriate
RvMsg fields. Applications that cannot, or do not wish to use the TIB/Adapter for Web
API, may provide their own custom code to marshall and unmarshall these fields and
transmit the reply message to the TIB/Adapter for Web servlet.
The return address of the servlet that sent the request is not a field in either the request or
reply message. The servlet uses RvSender::sendRequest() to send the request to your
service instance and create an inbox listener to receive your reply. When you receive a
request, your RvDataCallback::onData() method is called and given an RvSender to
use to send the reply.
Applications that are AE 3.0 wire format aware, and have no need to inspect or
manipulate HTTP protocol information, need only concern themselves with the
^-delimited AE 3.0 wire format fields. POST data will appear in the request msg ^data^
field, and the ^data^ field of the reply message carries the reply data payload.

Page 320 TIB/Adapter for Web User’s Guide

 Appendix D TIB/Rendezvous 5.x Facilities

Request and Reply RvMsg Formats

In the following tables, the TAWrvMsgFLD column provides the class member constants in
Java. Use the constants in TAWrvMsg.h found in the include directory and program
accordingly using the TIB/Rendezvous API.

Table 4 RvMsg fields common to both request and reply messages

TAWrvMsgFLD RvMsg field Rv Type Description

PFMT ^pfmt^ RVMSG_INT(2) For pre AE 3.0 wire format

compatibility. Constant value
10.
VER ^ver^ RVMSG_INT(2) Wire format version. 30 for AE
3.0
TYPE ^type^ RVMSG_INT(2) Wire Format ^data^ type 10
(string) or 1 (RvMsg)

Table 5 Request message RvMsg fields

TAWrvMsgFLD RvMsg field Rv type Description

DATA ^data^ RVMSG_STRING Request data from the HTTP

client.
HTTP_METHOD HTTPmethod RVMSG_STRING From HTTP request-line: GET
or POST
HTTP_URI HTTPuri RVMSG_STRING From HTTP request-line. For
example: /foo/bar.tibrv
HTTP_VERSION HTTPversion RVMSG_STRING From HTTP request-line. For
example: HTTP/1.0
HTTP_HEADERS HTTPheaders RVMSG_RVMSG Name/value pairs
corresponding to HTTP
general, request, or entity
headers.

TIB/Adapter for Web User’s Guide Page 321

Request and Reply RvMsg Formats
Table 5 Request message RvMsg fields
TAWrvMsgFLD RvMsg field
URL_PATH URLpath
URL_RESOURCE URLresource
URL_PARAMETE URLparameters
RS
VERSION_CODE TAWversion
Page 322
Rv type Description
RVMSG_STRING From HTTP request-line. For
example: given the URI
//foo/bar/baz.html,
URLpath is //foo/bar
RVMSG_STRING From HTTP request-line. For
example: given the URI
//foo/bar/baz.html,
URLresource is baz.html.
RVMSG_RVMSG From HTTP request-line. For
example: given the URI
//foo/bar/baz.tibrv?p1=v1
&p2=v2, URLparameters will
be an RvMsg containing fields
p1, and p2, with corresponding
values v1, and v2.
RVMSG_INT Inserted by API to assist
interoperation between TAW
versions.
TIB/Adapter for Web User’s Guide
 Appendix D TIB/Rendezvous 5.x Facilities

Table 6 Reply RvMsg fields

TAWrvMsgFLD RvMsg field Rv type Description

DATA ^data^ RVMSG_STRING or Response data from

HTTP_STATUS_ HTTPstatusCode
CODE
HTTP_REASON_ HTTPreasonPhrase
PHRASE
HTTP_HEADERS HTTPheaders
VERSION_CODE TAWversion
HTTP_CONTENT HTTPcontentType
_TYPE
RVMSG_OPAQUE
the service instance.
Most web clients will
require that the mime
type be specified in a
Content-Type header
in HTTP headers field
of this message.
RVMSG_INT HTTP status code. For
example: 200
RVMSG_STRING Message associated
with HTTPstatusCode.
For example, OK is
typical for 200.
RVMSG_RVMSG Name/value pairs
corresponding to
response headers.
RVMSG_INT Inserted by API to
assist interoperation
between TIB/Adapter
for Web versions.
RVMSG_STRING HTTP content type,
inserted by the API so
that the servlet can set
the content type
directly.

TIB/Adapter for Web User’s Guide Page 323

RVDQ Service Pools

RVDQ Service Pools

In some applications the message traffic can exceed the capacity of a single service
instance. A service pool can handle a large amount of message traffic. A service pool is a
collection of running applications that use Rendezvous Distributed Queues for
load-balancing requests and fault-tolerance.
Each server application in the pool listens to the same request subject, and
TIB/Rendezvous ensures that only one server receives any particular request. At any
point in time, one of the servers in the pool is the scheduler, and the others are workers.
RVDQ takes care of promoting a worker to a scheduler should the scheduler crash or
otherwise become non-responsive. When a request is issued, the scheduler determines
which server to forward the request to based upon RVDQ tuning parameters, as
described in TIB/Rendezvous documentation.

Setting up RVDQ Service Pools

While you can use the RVDQ API methods directly to set up a service pool, both the C++
and Java APIs that are provided with TIB/Adapter for Web make it easier for you to do
so. The APIs also make it possible for the initial client request to be directed to a service
pool member, according to load-balancing considerations, and for succeeding client
requests to bypass the RVDQ scheduler to maintain a session with the same pool member.
To create a service pool you follow the same basic steps as when you are setting up a
single queue processor, but when you instantiate the TAWrvService subclass that you
have defined, you provide it with a RvCmqSession that is used to participate in the service
pool. For more information about service pools and RVDQ-based load balancing, please
refer to the TIB/Rendezvous distributed queue documentation. The worldhello example
program illustrate the use of a service pool using RVDQ. The C++ version is annotated on
page 250. The Java version is annotated on page 304.

Page 324 TIB/Adapter for Web User’s Guide

 Appendix D TIB/Rendezvous 5.x Facilities

Creating Sessions within RVDQ Service Pools

When a client initially makes a request, one application in the service pool, acting as the
RVDQ scheduler, forwards the request to a worker instance, which invokes your service’s
onRequest method to process the request. The initial request is made to a request subject,
just as it would be for a non-RVDQ service. Part of the reply includes the worker’s direct
request subject, which allows the client to make requests directly to this worker in future,
without any intervention by the RVDQ scheduler. When a worker has specified a direct
request subject to a client, it will also be listening for requests on that subject from then on.
The TIB/Adapter for Web APIs support the notion of the direct request subject as an
additional subject that is unique to each worker instance. The direct request subject is
typically used when worker applications need to maintain state on the behalf of
individual clients. The client doesn't care which worker is initially assigned to its request,
but does require that follow-up requests be directed to the same worker.
For example, suppose each member of your pool is designed to present data to a client on
a page-at-a-time basis. The requesting client doesn't care which worker handles its initial
request, but it does need to get back to the same worker if it wants the next or previous
page. In this scenario, the worker's reply to the initial request will include the direct
request subject. The client uses this subject to make subsequent requests to the same
worker, who is keeping track of what page it last sent to the client.
The example program hellogoodbye shows how this works. The C++ version is
annotated on page 254. The Java version is annotated on page 307.

TIB/Adapter for Web User’s Guide Page 325

RVDQ Service Pools

Page 326 TIB/Adapter for Web User’s Guide

Index B
Building service applications 4

A C
APSvc C++ RV 6 92 Client, non GUI 41
appendToHeartbeat() 94 Code
APSvc() 93 FileSvc Java RV 5 301
disable() 95 filesvc.cc RV 5 246
enable() 96 filesvc.cc RV 6 109
init() 97 FileSvc.java RV 6 183
onMsg() 98 Compiler support 11
onTimer() 99 Compiling service examples
sendHeartbeat() 100 C++ RV 5 243
start() 101 C++ RV 6 104
startHeartbeating() 102 Java RV 5 298
terminate() 103 Java RV 6 179
APSvc Java RV 6 158 Configuration information
appendToHeartbeat() 159 retrieving through TIB/Hawk 54
disable() 160 Configuration properties
enable() 161 retrieving through TIB/Hawk 55
init() 162 Configuring
run() 163 IIS with JRun 2.3 17
terminate() 164 IIS with JRun 3.0 22
APSvcImpl Java RV 6 165 iPlanet Web Server 30
appendToHeartbeat() 168 service specific defaults 38
APSvcImpl() 167 TAW Servlet JRun 2.3 17
disable() 169 TAW Servlet JRun 3.0 23
enable() 170 TIB/Rendezvous parameters 42
init() 171 Creating
onMsg() 173 sessions within RVDQ RV 5 325
onTimer() 174 sessions within RVDQ RV 6 317
run() 175
sendHeartbeat() 176
startHeartbeating() 177
terminate() 178 D
Auto-Discovery process 48
Debug level
setting from TIB/Hawk 63

TIB/Adapter for Web User’s Guide Page 327

Index
DebugLevel, setting
Setting, debug level 63
E
Examples
file service C++ RV 6 108
file service Java RV 6 182
HelloGoodbye Java RV 5 307
MultiDispatcher service C++ RV 6 121
MultiDispatcher service Java RV 6 190
Raw Service Java RV 6 196
service list C++ RV 5 243
service list C++ RV 6 67
services list Java RV 5 298
services list Java RV 6 131
simple service C++ RV 6 105
simple service Java RV 6 180
simple service registry C++ RV 6 125
simple service registry Java RV 6 193
SimpleSvc Java RV 5 299
WorldHello C++ RV 6 112
WorldHello Java RV 5 304
WorldHello Java RV 6 185
F L
Fault tolerance 4
G
getConfig(), TIB/Hawk method 54
getConfigProperties, TIB/Hawk method 55
getDebugLevel(), TIB/Hawk method 56
getDebugSubject(), TIB/Hawk method 57
getServletContext(), TIB/Hawk method 58
Page 328
getStatus(), TIB/Hawk method 59
getStatus, TIB/Hawk method 59
getVersion(), TIB/Hawk method 60
GUI Client (Web Browser) 38
H
HelloGoodbye Java RV 6 187
HelloGoodbye service C++ RV 6 116
hellogoodbye.cc RV 5 254
hellogoodbye.cc RV 6 117
HelloGoodbye.java RV 6 188
I
Installation
and configuration 43
on Unix 13
on Windows NT 12
prerequisites, Windows NT 12
internalError 40
Invoking microagent methods 49
Licenses
for TIB/Rendezvous 10
Load balancing 4
M
Mapping arbitrary URLs 43
Microagents 52
multiDispatcher.cc RV 6 122
TIB/Adapter for Web User’s Guide

O T
onUnsolictedMsg(), TIB/Hawk method 61
Optional software 11
R getHttpRequestHeader() 231
Repository dat file 42
Request
and reply RvMsg formats 321
and reply TibrvMsg formats 313
RVDQ service pool 7
semantics 3
service registry pool 7
syntax 7
TAW service pool 7
RVDQ
based services 66
scheduler 68
service pools RV 5 324
service pools RV 6 316
S getHttpHeaders() 85
serviceNotUPURL 40
Session parameters, RV 42
setDebugLevel(), TIB/Hawk method 62
setDebugSubject(), TIB/Hawk method 64
Starting
TIB/Hawk software on Unix 47
TIB/Hawk software on Windows NT 47
Supported
operating systems 10
web servers 10
Syntax
request 7
TIB/Adapter for Web User’s Guide
Index
taw5config.dat 42
TAWrvException Java RV 6 157
TAWrvRequest C++ RV 5 221
getHttpMethod() 226
getHttpRequestEntityBody() 229
getHttpRequestHeaders() 242
getHttpUri() 227
getHttpVersion() 228
getProtocolVersion() 238
getReplySubject() 223
getRvdqSenderName() 235
getRvdqSequenceNumber() 236
getUrlParameter() 230
getUrlParameters() 241
getUrlPath() 224
getUrlResource() 225
isValid() 240
reply() 237
setHttpReasonPhrase() 239
setHttpReplyEntityBody() 232
setHttpReplyHeader() 233
TAWrvRequest C++ RV 6 83
getHttpHeader() 85
getHttpMethod() 86
getHttpReplyHeader() 87
getHttpReplyHeaders() 87
getHttpReplyOpaqueEntityBody() 87
getHttpReplyReasonPhrase() 87
getHttpReplyStatusCode() 87
getHttpReplyStringEntityBody() 87
getHttpUri() 86
getHttpVersion() 86
getProtocolVersion() 86
getReplyMsg() 87
getReplyProtocolVersion() 87
getUrlParameter() 86
getUrlParameters() 86
getUrlPath() 86
Page 329
Index
getUrlResource() 86
isValid() 88
reply() 89
setHttpReplyHeader() 90
setHttpReplyOpaqueEntityBody() 90
setHttpReplyReasonPhrase() 90
setHttpReplyStatus() 90
setHttpReplyStatusCode() 90
setHttpReplyStringEntityBody() 91
TAWrvRequest() 84
TAWrvRequest Java RV 5 276
getHttpMethod() 281
getHttpRequestEntityBody() 284
getHttpRequestHeader() 287
getHttpUri() 282
getHttpVersion() 283
getProtocolVersion() 296
getReplySubject() 278
getRvdqSenderName() 292
getUrlParameter() 285
getUrlParameters() 286
getUrlPath() 279
getUrlResource() 280
reply() 294
setHttpReasonPhrase() 297
setHttpReplyEntityBody() 289
setHttpReplyHeader() 290
setHttpStatusCode() 291
TAWrvRequest Java RV 6 147
getHttpHeader() 150
getHttpHeaders() 151
getHttpMethod() 151
getHttpReplyEntityBody() 152
getHttpReplyHeader() 152
getHttpReplyHeaders() 152
getHttpReplyReasonPhrase() 152
getHttpReplyStatusCode() 152
getHttpUri() 151
getHttpVersion() 151
getProtocolVersion() 151
getReplyMsg() 152
getReplyProtocolVersion() 152
Page 330
getUrlParameter() 151
getUrlParameters() 151
getUrlPath() 151
getUrlResource() 152
reply( entityBody, statusCode,
reasonPhrase) 154
reply() 153
reply(entityBody) 153, 154
reply(entityBody, statusCode) 153, 154
reply(entityBody, statusCode,
reasonPhrase) 154
setHttpReplyEntityBody(body) 155
setHttpReplyHeader(name value) 155
setHttpReplyReasonPhrase( phrase) 155
setHttpReplyStatus(code, phrase) 155
setHttpReplyStatusCode(code) 156
TAWrvRequest() 149
TAWrvService C++ RV 5 204
~TAWrvService() 208
disableRequests() 216
enableRequests() 215
getDirectRequestSubject() 213
getErrorMsg() 220
getRequestSubject() 214
getRvSession() 219
isEnabled() 217
isValid() 218
onDirectRequest() 210
onRequest() 209
setDirectRequestSubject() 212
setRequestSubject() 211
TAWrvService() 206
TAWrvService C++ RV 6 68
~TAWrvService() 72
disableRequests() 73
enableRequests() 74
fence() 75
getDirectRequestSubject() 76
getDispatchQueue() 76
getErrorMsg() 76
getRequestSubject() 76
getTibrvCmQueueTransport() 76
TIB/Adapter for Web User’s Guide
 Index

getTibrvTransport() 76 TAWrvService(transport) 135

isEnabled() 77 TAWrvService(transport, queue) 135
isValid() 78 TAWrvService(transport, queue,
onDirectMsg() 79 requestSubject) 135
onMsg() 80 TAWrvService(transport, queue, requestSub-
setDirectRequestSubject() 81 ject, directRequestSubject) 136
setRequestSubject() 82 TIB/Hawk
TAWrvService() 70 version supported 11
TAWrvService Java RV 5 261 TIB/Hawk methods
disableRequests() 272 getConfig 54
getDirectRequestSubject() 269 getConfigProperties 55
getRequestSubject() 270 getStatus 59
getRvCmqSession() 275 setDebugLevel 62
getRvSession() 274 timeout 40
isEnabled() 273 timeoutURL 40
onDirectRequest() 266
onRequest() 265
setDirectRequestSubject() 268
setRequestSubject() 267 U
TAWrvService() 263
TAWrvService Java RV 6 132 URLs constructed by HTTP client 7
disableRequests() 145
enableRequests() 144
getDirectRequestSubject() 139
getDispatchQueue() 139 W
getRequestSubject() 139
getTibrvCmQueueTransport() 139 Web servers, supported 10
getTibrvTransport() 139
isEnabled() 146
onDirectMsg() 141
onMsg() 140
setDirectRequestSubject() 143
setRequestSubject() 142
TAWrvService() 134
TAWrvService(cmqQueueTransport) 136
TAWrvService(cmqQueueTransport,
queue) 136
TAWrvService(cmqQueueTransport,
queue, requestSubject) 137
TAWrvService(cmqQueueTransport,
queue, requestSubject,
directRequestSubject) 137

TIB/Adapter for Web User’s Guide Page 331

Index

Page 332 TIB/Adapter for Web User’s Guide