JBI Specification

Java™ Business Integration (JBI) 1.
Final Release
August 17, 2005
Editors:
Ron Ten-Hove
Peter Walker
Comments to: [email protected]
Sun Microsystems, Inc.

4150 Network Circle
Santa Clara, CA 95054 USA
August 17, 2005 Java Business Integration 1.0 Final Release ii
Specification: JSR 208, Java Business Integration (JBI)("Specification")
Status: Final Release
Release: August 23, 2005
Copyright 2005 SUN MICROSYSTEMS, INC.
All rights reserved.
IF YOU OBTAINED ACCESS TO THIS SPECIFICATION BY MEANS OF A LICENSE FROM SUN THAT STATED THE
SPECIFICATION WAS PROVIDED TO YOU ONLY FOR EVALUATION PURPOSES, OR IF YOU OBTAINED ACCESS TO
THIS SPECIFICATION BY OTHER MEANS BUT ONLY WISH TO USE THE SPECIFICATION FOR EVALUATION
PURPOSES, THEN FOLLOWING PROVISIONS APPLY:
LIMITED EVALUATION LICENSE
Sun hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the right to sublicense),
under Sun's applicable intellectual property rights to view, download, use and reproduce the Specification only for the purpose of
internal evaluation. This includes (i) developing applications intended to run on an implementation of the Specification, provided
that such applications do not themselves implement any portion(s) of the Specification, and (ii) excerpting brief portions of the
Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the
aggregate constitute a significant portion of the Technology. No license of any kind is granted hereunder for any other purpose
including, for example, creating and distributing implementations of the Specification, modifying the Specification (other than to
the extent of your fair use rights), or distributing the Specification to third parties. Also, no right, title, or interest in or to any
trademarks, service marks, or trade names of Sun or Sun's licensors, Sun or the Sun's licensors is granted hereunder. If you wish to
create and distribute an implementation of the Specification, a license for that purpose is available at http://www.jcp.org. The
foregoing license is expressly conditioned on your acting within its scope, and will terminate immediately without notice from Sun
if you breach the Agreement or act outside the scope of the licenses granted above. Java, and Java-related logos, marks and names
are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS". SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE, NON-INFRINGEMENT (INCLUDING AS A CONSEQUENCE OF ANY PRACTICE OR
IMPLEMENTATION OF THE SPECIFICATION), OR THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE
FOR ANY PURPOSE. This document does not represent any commitment to release or implement any portion of the
Specification in any product. In addition, the Specification could include technical inaccuracies or typographical errors.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY
DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL,
INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF
THE THEORY OF LIABILITY, RELATED IN ANY WAY TO YOUR HAVING OR USING THE SPECIFICATION, EVEN IF
SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
RESTRICTED RIGHTS LEGEND
U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime
contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be
only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense
(DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
REPORT
If you provide Sun with any comments or suggestions concerning the Specification ("Feedback"), you hereby: (i) agree that such
Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide,
fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and
use without limitation the Feedback for any purpose.
GOVERNING LAW
Any action relating to or arising out of this Agreement will be governed by California law and controlling U.S. federal law. The
U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.
August 17, 2005 Java Business Integration 1.0 Final Release iii
IF YOU OBTAINED ACCESS TO THIS SPECIFICATION BY MEANS OF A LICENSE FROM SUN THAT AUTHORIZED
YOU TO CREATE AND/OR DISTRIBUTE INDEPENDENT IMPLEMENTATIONS OF THE SPECIFICATION, OR IF YOU
OBTAINED ACCESS TO THIS SPECIFICATION BY OTHER MEANS BUT WISH TO USE THE SPECIFICATION TO
CREATE AND/OR DISTRIBUTE INDEPENDENT IMPLEMENTATIONS OF THE SPECIFICATION, THEN the
FOLLOWING PROVISIONS APPLY:
LIMITED LICENSE GRANTS
1. License for Evaluation Purposes. Sun hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited
license (without the right to sublicense), under Sun's applicable intellectual property rights to view, download, use and reproduce
the Specification only for the purpose of internal evaluation. This includes (i) developing applications intended to run on an
implementation of the Specification, provided that such applications do not themselves implement any portion(s) of the
Specification, and (ii) excerpting brief portions of the Specification in oral or written communications which discuss the
Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Technology.
2. License for the Distribution of Compliant Implementations. Sun also grants you a perpetual, non-exclusive, non-transferable,
worldwide, fully paid-up, royalty free, limited license (without the right to sublicense) under any applicable copyrights or, subject
to the provisions of subsection 4 below, patent rights it may have covering the Specification to create and/or distribute an
Independent Implementation of the Specification that: (a) fully implements the Specification including all its required interfaces
and functionality; (b) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or
protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/
authorized by the Specification or Specifications being implemented; and (c) passes the Technology Compatibility Kit (including
satisfying the requirements of the applicable TCK Users Guide) for such Specification ("Compliant Implementation"). In
addition, the foregoing license is expressly conditioned on your not acting outside its scope. No license is granted hereunder for
any other purpose (including, for example, modifying the Specification, other than to the extent of your fair use rights, or
distributing the Specification to third parties). Also, no right, title, or interest in or to any trademarks, service marks, or trade names
of Sun or Sun's licensors, Sun or the Sun's licensors is granted hereunder. Java, and Java-related logos, marks and names are
trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
3. Pass-through Conditions. You need not include limitations (a)-(c) from the previous paragraph or any other particular "pass
through" requirements in any license You grant concerning the use of your Independent Implementation or products derived from
it. However, except with respect to Independent Implementations (and products derived from them) that satisfy limitations (a)-(c)
from the previous paragraph, You may neither: (a) grant or otherwise pass through to your licensees any licenses under Sun's
applicable intellectual property rights; nor (b) authorize your licensees to make any claims concerning their implementation's
compliance with the Spec in question.
4. Reciprocity Concerning Patent Licenses.
a. With respect to any patent claims covered by the license granted under subparagraph 2 above that would be infringed by all
technically feasible implementations of the Specification, such license is conditioned upon your offering on fair, reasonable and
non-discriminatory terms, to any party seeking it from You, a perpetual, non-exclusive, non-transferable, worldwide license under
Your patent rights which are or would be infringed by all technically feasible implementations of the Specification to develop,
distribute and use a Compliant Implementation.
b With respect to any patent claims owned by Sun and covered by the license granted under subparagraph 2, whether or not their
infringement can be avoided in a technically feasible manner when implementing the Specification, such license shall terminate
with respect to such claims if You initiate a claim against Sun that it has, in the course of performing its responsibilities as the Sun,
induced any other entity to infringe Your patent rights.
c Also with respect to any patent claims owned by Sun and covered by the license granted under subparagraph, where the
infringement of such claims can be avoided in a technically feasible manner when implementing the Specification such license,
with respect to such claims, shall terminate if You initiate a claim against Sun that its making, having made, using, offering to sell,
selling or importing a Compliant Implementation infringes Your patent rights.
5. Definitions. For the purposes of this Agreement: "Independent Implementation" shall mean an implementation of the
Specification that neither derives from any of Sun's source code or binary code materials nor, except with an appropriate and
separate license from Sun, includes any of Sun's source code or binary code materials; "Licensor Name Space" shall mean the
public class or interface declarations whose names begin with "java", "javax", "com.sun" or their equivalents in any subsequent
naming convention adopted by Sun through the Java Community Process, or any recognized successors or replacements thereof;
and "Technology Compatibility Kit" or "TCK" shall mean the test suite and accompanying TCK User's Guide provided by Sun
which corresponds to the Specification and that was available either (i) from Sun's 120 days before the first release of Your
August 17, 2005 Java Business Integration 1.0 Final Release iv

Independent Implementation that allows its use for commercial purposes, or (ii) more recently than 120 days from such release but
against which You elect to test Your implementation of the Specification.
This Agreement will terminate immediately without notice from Sun if you breach the Agreement or act outside the scope of the
licenses granted above.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS". SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE, NON-INFRINGEMENT (INCLUDING AS A CONSEQUENCE OF ANY PRACTICE OR
IMPLEMENTATION OF THE SPECIFICATION), OR THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE
FOR ANY PURPOSE. This document does not represent any commitment to release or implement any portion of the
Specification in any product. In addition, the Specification could include technical inaccuracies or typographical errors.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY
DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL,
INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF
THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED IN ANY WAY TO YOUR HAVING, IMPELEMENTING
OR OTHERWISE USING USING THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.
You will indemnify, hold harmless, and defend Sun and its licensors from any claims arising or resulting from: (i) your use of the
Specification; (ii) the use or distribution of your Java application, applet and/or implementation; and/or (iii) any claims that later
versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this
license.
RESTRICTED RIGHTS LEGEND
U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime
contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be
only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense
(DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
REPORT
If you provide Sun with any comments or suggestions concerning the Specification ("Feedback"), you hereby: (i) agree that such
Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide,
fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and
use without limitation the Feedback for any purpose.
GOVERNING LAW
Any action relating to or arising out of this Agreement will be governed by California law and controlling U.S. federal law. The
U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.
August 17, 2005 Java Business Integration 1.0 Final Release v

August 17, 2005 Java Business Integration 1.0 Final Release vi
Contents
1 Preface ........................................................................................................... xi
Changes Since the Public Draft Review .................................................................................................... xi
2 Introduction ................................................................................................... 1
Summary ..................................................................................................................................................... 1
Scope ........................................................................................................................................................... 1
Target Audience .......................................................................................................................................... 2
Organization ................................................................................................................................................ 2
Conventions ................................................................................................................................................ 2
Expert Group ............................................................................................................................................... 3
Status of this Document .............................................................................................................................. 4
3 Overview ......................................................................................................... 5
Definitions ................................................................................................................................................... 7
Rationale & Assumptions ........................................................................................................................... 7
Goals ........................................................................................................................................................... 8
Relationship to other Specifications and Technologies .............................................................................. 8
Roles ............................................................................................................................................................ 8
4 Architecture of the JBI Environment ........................................................ 11

WSDL-based Messaging Model ............................................................................................................... 11
Normalized Message ................................................................................................................................. 13
High-Level Architecture ........................................................................................................................... 14
Normalized Message Exchange ................................................................................................................ 15
Management .............................................................................................................................................. 16
Component Framework ............................................................................................................................. 17
Normalized Message Router ..................................................................................................................... 17
Components .............................................................................................................................................. 17
Examples ................................................................................................................................................... 18
5 Normalized Message Router ....................................................................... 21

Key Concepts ............................................................................................................................................ 21
Elements of a Message Exchange ............................................................................................................. 27
Normalized Message ................................................................................................................................. 28
NMR Design ............................................................................................................................................. 29
NMR API .................................................................................................................................................. 37
6 Management ................................................................................................. 59
Overview ................................................................................................................................................... 59
Key Concepts ............................................................................................................................................ 60
Packaging .................................................................................................................................................. 64
Installation Service .................................................................................................................................... 71
Component Life Cycle .............................................................................................................................. 74
Deployment Service .................................................................................................................................. 78
Service Unit Life Cycle ............................................................................................................................. 81
Service Assembly Life Cycle .................................................................................................................... 82
MBean Status and Result Strings .............................................................................................................. 83
Ant Script Support .................................................................................................................................... 86
August 17, 2005 Java Business Integration 1.0 Final Release vii
Contents
7 Component Framework .............................................................................. 97

Component-Supplied Management Functions .......................................................................................... 98
JBI-Supplied Environment Features ....................................................................................................... 101
Class Loading .......................................................................................................................................... 103
Error Indication ....................................................................................................................................... 107
8 javax.jbi ...................................................................................................... 109

JBIException ........................................................................................................................................... 110
9 javax.jbi.component .................................................................................. 113

Bootstrap ................................................................................................................................................. 114
Component .............................................................................................................................................. 116
ComponentContext ................................................................................................................................. 119
ComponentLifeCycle .............................................................................................................................. 126
InstallationContext .................................................................................................................................. 128
ServiceUnitManager ............................................................................................................................... 131
10 javax.jbi.management ............................................................................... 135

AdminServiceMBean .............................................................................................................................. 136
ComponentLifeCycleMBean .................................................................................................................. 139
DeploymentException ............................................................................................................................. 141
DeploymentServiceMBean ..................................................................................................................... 143
InstallationServiceMBean ....................................................................................................................... 149
InstallerMBean ........................................................................................................................................ 151
LifeCycleMBean ..................................................................................................................................... 153
MBeanNames .......................................................................................................................................... 155
11 javax.jbi.messaging .................................................................................... 157

DeliveryChannel ..................................................................................................................................... 158
ExchangeStatus ....................................................................................................................................... 162
Fault ........................................................................................................................................................ 164
InOnly ..................................................................................................................................................... 165
InOptionalOut ......................................................................................................................................... 167
InOut ....................................................................................................................................................... 169
MessageExchange ................................................................................................................................... 171
MessageExchange.Role .......................................................................................................................... 179
MessageExchangeFactory ....................................................................................................................... 180
MessagingException ............................................................................................................................... 183
NormalizedMessage ................................................................................................................................ 185
RobustInOnly .......................................................................................................................................... 188
12 javax.jbi.servicedesc .................................................................................. 191

ServiceEndpoint ...................................................................................................................................... 192
13 Almanac ...................................................................................................... 197

14 Future Directions ....................................................................................... 205
15 Appendix: Use of Transactions ................................................................. 207
Quality of Service ................................................................................................................................... 207
Reliability in Message Exchange ............................................................................................................ 208
Transactional Message Exchange ........................................................................................................... 211
August 17, 2005 Java Business Integration 1.0 Final Release viii
Contents
16 References ................................................................................................... 215

17 Index ........................................................................................................... 217
Colophon ..................................................................................................... 227
August 17, 2005 Java Business Integration 1.0 Final Release ix

Contents
August 17, 2005 Java Business Integration 1.0 Final Release x

CHAPTER 1
Preface
This is the Public Final version of the Java Business Integration (JBI) 1.0 specification.
Please address comments about this specification to [email protected].
1.1 Changes Since the Public Draft Review

The following list is a summary of changes made to this specification since the Public Draft Review, issued in
March, 2005. Numerous editorial changes have been made as well.
• The Ant tasks for scripted system management have been defined.
• Management tasks for handling the service assembly life cycle have been added.
• Class loader requirements have been restated as ordering rules, rather than a mandated class loader
hierarchy
• An option for "self-first" class loader delegation has been added
• WSDL 1.1 can now be used by service providers to describe their services.
• Dynamic endpoint resolution and creation are now supported.
• Methods for creating MessageExchange instances have been put into a separate
MessageExchangeFactory, rather than as part of the DeliveryChannel.
• WSDL 1.1 normalization rules have been added.
• Connection metadata support has been added to deployment packaging.
August 17, 2005 Java Business Integration 1.0 Final Release xi

Preface
August 17, 2005 Java Business Integration 1.0 Final Release xii
CHAPTER 2
Introduction
2.1 Summary
Enterprise application integration (EAI) and business-to-business integration (B2B) solutions have traditionally
required the use of non-standard technologies to create functional systems. This has required end users to either
“lock in” to a single vendor of such technologies, or create their own. Each approach has disadvantages. No
single vendor can cover the vast functional space of EAI and B2B (consider the thousands of applications and
protocols to be supported). This leaves users of integration technologies in the uncomfortable position
of selecting less than ideal solutions to their integration problems, and paying dearly for them.
Java™ Business Integration (JBI) seeks to address this problem by creating a standards-based architecture for
integration solutions. This infrastructure allows third-party components to be “plugged in” to a standard
infrastructure, and allows those components to interoperate in a predictable, reliable fashion despite being
produced by separate vendors. It is anticipated that this ability to interoperate will create a multivendor
“ecosystem” which will give rise to large pool of integration-related technologies that can be sourced by end
users. In addition, this ecosystem will foster new innovations in integration technologies, since it will permit
innovators to concentrate on a particular technology or problem area, without having to worry about providing
all the other pieces needed to build a complete integration solution.
Every integration problem is unique; an appropriate combination of JBI-compliant components will provide a
solution that is sized appropriately to the problem at hand. By avoiding lock-in to a particular vendor of
integration technologies, the user is free to choose components that provide the particular functions that he or
she needs, and be assured that a functional integration solution can be assembled from those pieces.
In the past, attempts to compose third-party components into systems that have the attributes required of
enterprise systems have not been very successful. JBI addresses this by adopting a service-oriented architecture
(SOA), which maximizes the decoupling between components, and creates well-defined interoperation
semantics founded on standards-based messaging. The SOA approach creates many other benefits that are
applicable to enterprise integration solutions.
2.2 Scope
The membership of the JSR 208 Expert group is largely composed of business-oriented engineers and designers
and this specification reflects their biases, priorities, requirements and experiences. In general, this specification
is scoped to the needs and requirements of business solution providers.
August 17, 2005 Java Business Integration 1.0 Final Release 1

Introduction
This specification is considered to be complimentary to the J2EE™ Platform specification. JBI does not require
the J2EE™ platform though there is a clear dependency on the J2SE™ platform. It is worth noting that the
J2EE™ platform may choose to reference this specification in the future.
2.3 Target Audience

The primary audience for this specification is system level software engineers who will develop the following:
• implementations of the JBI infrastructure itself,
• the “plug in” components that provide
• communications protocol support,
• business logic,
• transformation engines,
• intelligent message routing,
• etc.
This specification is not appropriate for application developers or business analysts. It is hoped that this
specification will facilitate the development of standard service composition tools and services targeted
specifically at this group.
2.4 Organization
This document is organized such that the initial sections provide some context and rationale for the JSR 208
initiative within the framework of the Java Community Process. Subsequent sections provide use-cases and
relevant examples as a clarification of the Application Programming Interfaces (APIs) and Service Provider
Interfaces (SPIs) specified in subsequent sections of the document.
2.5 Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD
NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in
[RFC 2119]
Java code and XML fragments are formatted as shown in Listing 1
package com.foo.example;
class Runner {
public static void main(String[] args) {
System.out.println("Hello, Universe!");
}
}
Listing 1 Example code fragment

Introduction
This specification uses a number of XML namespace prefixes throughout; they are listed in Table 1
Prefix Namespace Description

http://java.sun.com/xml/ns/jbi Jbi descriptors for installation and
jbi
deployment packages
http://www.w3.org/2004/08/wsdl Web services description language 2.0
wsdl
last-call draft
Table 1 XML namespace prefixes
2.6 Expert Group

Without the contributions, input, and general guidance of the JSR 208 Expert Group this specification would
not have been possible. Thanks are extended to the following organizations for the support of their experts (past
and present) and contributions to this JSR:
• Apache Software Foundation – James Strachan
• Sid Askary
• Borland Software Corp. – Ramanathan Ravikumar
• Cap Gemini – Steve Jones
• Collaxa – Edwin Khodabakchian
• DPWN SOP Group – Andreas Mattes, Ramtin Mesbahipour
• Fujitsu – Keith Swenson
• Intalio, Inc. – Assaf Arkin
• IONA – Peter Cousins
• IOPSIS Software Inc. – Rajesh Pradhan
• JBoss – Tom Baeyens
• Jie Liu
• Nokia Corp. – Sudhanshu Pant
• Novell, Inc. – Greg Ritzinger
• Oak Grove Systems – Charles Ames
• Oracle – Sastry Malladi, Bill Eidson, Hal Hildebrand, Rob Giardina
• Timothy Potter
• Research In Motion, Ltd. – Michael Shenfield
• SAP AG – Sanjay Patil
• SeeBeyond Technology Corp. – Pete Wenzel
• Sonic Software – David Chappell, Glen Daniels, Jaime Meritt
• Sun Microsystems, Inc. – Nick Kassem, Ron Ten-Hove, Keith Babo, Peter Walker
• Sybase – Bill Flood, Lance Waterman
• Tmax Soft, Inc. – Jongjin Choi

Introduction
• TIBCO Software Inc. – Scott Vorthmann

• Vignette – Dave Wilkinson
• WebMethods Corp. – Eduardo Saltelli
2.7 Status of this Document

This specification is the “Final Release” version of JBI 1.0. It is accompanied by a Reference Implementation
(RI), which provides an operational definition of this specification, and a Technology Compatibility Kit (TCK),
which verifies if an implementation conforms to this specification. Note that the RI and TCK are subject to
different licensing terms than this specification. See http://java.sun.com/integration for details.

CHAPTER 3
Overview
JBI defines an architecture that allows the construction of integration systems from plug-in components, that
Figure 1 Plug-in Construction of a System
interoperate through the method of mediated message exchange. The message exchange model is based on the
Figure 2 Mediated Message Exchange: high-level message sequence chart
web services description language 2.0 [WSDL 2.0] or 1.1 [WSDL 1.1].
Figure 1 illustrates, at a high level, the JBI concept of plug-in components. JBI provides specific interfaces for

Overview
use by a plug-in, while the plug-in provides specific interfaces for use by JBI. Components do not interact with
each other directly. Instead, as shown in Figure 2, JBI functions as an intermediary to route messages from
component to component. This separation of the participants in an exchange is key to decoupling service
providers from consumers, which is highly desirable in service-oriented architectures generally, and in
integration solutions in particular. This preserves flexibility, since consumer and provider are minimally
intertwined, and provides a key point for message processing and monitoring in JBI implementations. Note also
that this processing is inherently asynchronous; provider and consumer never share a thread. This also helps
keep components decoupled.
In this WSDL-based, service-oriented model, JBI plug-in components are responsible for providing and
consuming services. By providing a service, a component is making available a function or functions that can
be consumed by other components (or even itself). Such functions are modelled as WSDL 2.0 operations,
which involve the exchange of one or more messages. A set of four WSDL-defined, basic message exchange
patterns (MEPs) crisply defines the sequence of messages allowed during execution of an operation. This
shared understanding, between consumer and provider components, of the message exchange pattern is the
foundation of interoperability of such components in JBI.
The services provided by components (if any) are described to JBI by the component, using WSDL 1.1 or 2.0.
This provides an abstract, technology-neutral model of services using XML-based message exchanges. WSDL
also provides a mechanism for declaring additional service metadata of interest to service consumers and JBI
itself. Components can query JBI for the for the WSDL describing available services.
As shown in Figure 1, JBI components plug into what is termed the JBI framework. It is expected that such
components will be made available to end users from third parties, particularly where common or standardized
functions are needed in typical integration problems.
The components are divided into two distinct types:
• Service Engine (SE). SEs provide business logic and transformation services to other components, as well
as consume such services. SEs can integrate Java-based applications (and other resources), or applications
with available Java APIs.
• Binding Component (BC). BCs provide connectivity to services external to a JBI environment. This can
involve communications protocols, or services provided by Enterprise Information Systems (EIS
resources). BCs can integrate applications (and other resources) that use remote access technology that is
not available directly in Java.
Service engines and binding components can function as service providers, consumers, or both. (The distinction
between SEs and BCs is purely pragmatic, but is based on sound architectural principles. The separation of
business (and processing) logical from communications logic reduces implementation complexity, and
increases flexibility.)
In addition to a messaging system designed to promote component interoperability, JBI defines a management
structure, based on Java Management eXtensions (JMX). JBI provides standard mechanisms for:
• Installing components.
• Managing a component’s life cycle (stop/start etc.)
• Deploying service artifacts to components.
The last item requires some explanation. JBI components often function as a type of container, to which
artifacts can be deployed to add new service consumer or provider logic. For example, a service engine that
provides XSLT-based transformation services would have XSLT style sheets deployed to it, in order to add new
transformation operations. This process of adding such component-specific artifacts to an installed component
is called deployment, to distinguish it from component installation. JBI terms a collection of deployment
artifacts and associated metadata a service assembly. This type of collection of service-related artifacts and
metadata is referred as a composite service description (CSD) in some literature.

Overview
3.1 Definitions
JBI does not define a traditional application programming model. Instead, it embraces a service-oriented
approach to structuring enterprise functions, where JBI plug-in components function as service providers and
consumers. The APIs and SPIs defined in this specification are for the use of developers of service engines and
binding components that “plug in” to the JBI infrastructure, as described above.
As previously discussed, the term Service Engine (or SE) is used to refer to plug-in components that provide
business logic, transformational services, etc. Service engines can take a wide variety of forms, depending on
the type of functions they supply. In particular, some SEs can function as “containers,” presenting a unique
programming model to users. For example:
• An XSLT XML transformation engine can support multiple transformation types. In this case, the
programming interface is essentially the XSLT language itself.
• A WS-BPEL 2.0 business process execution engine. In this case, the programming interface is WS-BPEL
itself.
• An EJB container. In this case, the API is Java that conforms to the appropriate EJB specification.
Binding components provide the ability to use communications protocols to both access remotely provided
services, and allow remote service consumers to access services provided within the JBI environment. Protocols
can be as varied as the integration problems being solved require, but typical examples include
• SOAP over HTTP [http://www.ws-i.org/Profiles/BasicProfile-1.1.html],
• JMS/MOM [http://jcp.org/aboutJava/communityprocess/final/jsr914/index.html] and
• AS1/AS2 EDI [http://www.ietf.org/html.charters/ediint-charter.html] communications stacks.
A Binding Component may choose to implement one or more communications protocols, offering connectivity
services to SEs and thereby enabling SEs to expose their services to remote consumers as well as enabling the
consumption of remote services.
There are several distinct roles played by the various users of JBI:
• Integration Architect. This user designs the overall approach to solving integration problems. This
includes selecting JBI components to be used to provide connectivity and business logic.
• Integration Technologist. This user devises the particular services needed to solve an integration problem,
and configures a JBI system to integrate those services.
• System Administrator. This user installs, configures, monitors, and tunes the JBI system so that it
provides the designed integration services.
• JBI Component Developer. JBI components can be created by users, or by third parties. In either case, the
developer of JBI plug-ins must provide Java components that conform to particular contracts that are
defined in this specification.
These roles are elaborated upon in “Roles” on page 8
3.2 Rationale & Assumptions

The rationale for this specification is predicated on the following key assumptions, empirical data, anecdotal
evidence, and business requirements,
• J2EE™ Platform suppliers increasingly view Web Services as a central rather than a peripheral aspect of
their product offering

Overview
• The evolution of the Web Services standards is driving Service Integration to occur at a pace and at a level
requiring the inclusion of entirely new classes of “developers” trained not so much in procedural languages
but in emerging declarative vocabularies
• The need for supporting Service Composition vocabularies that depend heavily on WSDL [WSDL 2.0]
presents an opportunity to reach convergence on what is meant by an abstract business message, and more
specifically on what is meant by WSDL-defined messaging.
• By establishing a common abstract view of a normalized (business) message it becomes possible to
decouple a component-specific application programming model (used to design and develop business
logic) from the underlying communications infrastructure needed to support such logic.
3.3 Goals
The following are the primary goals of this specification:
• The establishment of a standard SPI for developers of service engines and binding components, known
collectively as JBI components.
• The development of an abstract protocol-neutral Message Exchange and Normalized Message (NM)
• Provision of a standard mechanism for Message Exchanges to flow between JBI components
• Establishment of a standard for the packaging of JBI components, as well as for deployment of service
artifacts to such components
• Definition of administrative and management hooks such that a diverse set of standard tools targeted at
specific problem domains can emerge over time
• Given the complexity and diversity of SE and BC implementations, it must be possible for different
vendors to deliver SEs, BCs or both. Such components must be able to interoperate reliably, and a system
constructed of such components (atop a JBI infrastructure) must be centrally manageable.
3.4 Relationship to other Specifications and Technologies

JBI implementations are dependent on either J2SE 1.4 or J2EE 1.4.
JBI makes use of Web Services Description Language ([WSDL 2.0] and [WSDL 1.1]) as both a service
description language and, in the case of WSDL 2.0, as a basic model for plug-in component interaction.
Interaction makes use of XML-based messages [XML 1.0]. XML processing follows the model developed for
JAX-RPC 2.0 [JAX-RPC 2.0], which is still under development at the time this was written. For this reason the
relationship between JAX-RPC 2.0 and JBI is informal; later versions of this specification may specify a formal
dependency on JAX-RPC 2.0.
JBI relies on Java Management eXtensions (JMX) [JMX 1.2].
JBI defines what is sometimes termed a “service container” in Enterprise Service Bus (ESB) systems [ESB].
3.5 Roles
A functionally rich integration product is required to deliver a wide range of critical components over and above
what a standard JBI environment requires. By design, JBI is silent about many necessary elements of a

Overview
compelling overall solution. For example, a SE should be viewed as a container hosting business logic that is
“programmed” using vocabularies ranging from annotated Java™ to XML (such as XSLT), none of which is
defined by JBI. JBI therefore assumes a number of different actors playing complimentary roles with the
common underlying objective of delivering an overall business solution.
3.5.1 Engine Developers

A JBI compatible SE implementation is required to implement the Normalized Message Router (NMR)
contract. In addition SE developers must implement the component life cycle and management interfaces, and,
if needed, a deployment interface. If the SE functions as a container, SE developers may provide whatever
tooling they feel appropriate for easing development of SE-specific artifacts.
3.5.2 Binding Developers

A JBI compatible BC implementation is required to implement the same contracts as an SE. Bindings are
typically distinct from engines, due to their use of protocols for remote access to, and provision of, services.
3.5.3 JBI Environment Providers

The suppliers of a JBI compatible environment must support the normative interfaces exposed in this
specification. JBI compatible implementations may choose to use the J2EE™ 1.4 or newer platform but are not
required to do so. If J2EE is not supported, then J2SE 1.4 or newer MUST be supported.
A JBI 1.0 compatible environment MUST support at least one implementation of a WS-I Basic Profile 1.1
[http://www.ws-i.org/Profiles/BasicProfile-1.1.html] compatible Binding Component.
A JBI compatible environment may choose to deliver a service engine implementation but are not required to
do so.
3.5.4 J2EE™ Platform Providers

J2EE™ Platform providers may choose to deliver a complete JBI environment including Service Engines,
Binding Components and application-level tooling. J2EE™ Platform providers are currently not required to
support JBI.
3.5.5 JBI Application Developers

A JBI application developer is essentially modeling, designing, developing and deploying business components
using vocabularies and tools that are defined by specific SE and BC implementations. The entire JBI
environment is therefore one-step removed from a JBI application developer.
Many such developers will be developing XML artifacts used to customize engines and bindings. This is not the
traditional model of a developer as used in the J2EE and J2SE domains, where the emphasis is on development
of Java code.

Overview

CHAPTER 4
Architecture of the JBI
Environment
JBI provides an environment in which plug-in components reside. The environment provides a set of services to
facilitate execution of provided services, interaction between components, as well as management of the overall
system created by a JBI installation and all installed components.
JBI provides for interoperation between plug-in components by means of message-based service invocation,
described using a standard service description language. This provides a consistent model of services that the
components can provide and consume.
JBI provides a set of services to facilitate management of the JBI environment, including the installed
components. This includes component installation and life cycle management services.
4.1 WSDL-based Messaging Model

JBI models services produced and consumed by components using Web Services Description Language
versions 1.1 and 2.0. Where terminology differs between these two versions, that of WSDL 2.0 is used.
WSDL provides a declarative model of message-based services on two levels:
• Abstract service model. A service is defined using an abstract messaging model, without reference to a
particular protocol or wire encoding.
• Concrete (bound) model. An abstract service that is bound to a particular protocol and communications
end point.
JBI uses the abstract service model as the main basis of component interactions. Components play one of two
roles in such interactions:
• Service Provider. The component that performs the given service (either directly or as a proxy for an
external provider).
• Service Consumer. The component that invokes a given service (either directly or as a proxy for a remote
consumer).
The WSDL model uses names to refer to the various components of the model. There are two types used:
• Qualified names. These names are pairs: an XML namespace (a URI), and a simple name. Qualified
names are used where universal uniqueness is desired.

Architecture of the JBI Environment
• Simple (non-qualified) names. These are names that do not have an associated XML namespace. These
are used in situations where uniqueness is either not needed, or has a non-global scope.
The WSDL component model is shown schematically in the figure below.The details of this model are
Figure 3 WSDL Component Model Schematic
discussed in the following subsections.
4.1.1 Abstract Service Model

WSDL service descriptions always include an abstract service model, which defines the following:
• Abstract message types. Message types define the structure and constraints for valid messages. This is
typically expressed using XML Schema. Messages fall into two categories: normal, and fault. Normal
messages are used for the normal, expected use of services, while fault messages apply to abnormal
processing conditions.
• Abstract operations. An operation is an interaction with a service that is defined in terms of normal (and
possibly fault) messages, exchanged between a service consumer and a service provider. An abstract
operation is defined in terms of:
• Operation name. A qualified name used to designate the operation.
• Message Exchange Pattern (MEP). The sequence, direction, and cardinality of messages sent between
the consumer and the provider. This includes both normal and fault messages.
• Message types for each message in the MEP.
• Abstract Service Type. A collection of related abstract operations is an abstract service type definition.
This is termed the “interface” in WSDL 2.0, and “portType” in WSDL 1.1, and referred to as the “interface”
in this specification. This should not be confused with the Java Language construction of the same name.
The interface is defined in terms of:

• Interface Name. A qualified name identifying the service type globally. The interface name is used
extensively in JBI as a service type identifier.
• Extended Interfaces. Service types can be defined as extensions of other service types, in a fashion that
is analagous to Java interfaces. Thus a service type may be composed of other service types.
4.1.2 Concrete Service Model

Concrete service descriptions in WSDL build upon the abstract service model, supplying information needed to
"map" the abstract definition to a particular communications protocol and communications endpoint. JBI bases
its component interaction model primarily on the abstract service model, thus giving it the desirable property of
being communications protocol neutral. However, to be consistent with the WSDL service model, component
interactions need to be defined using WSDL’s concreate service model. In JBI this is a very simple model, using
the abstract model "as is" wherever possible, thus creating a simple processing model for interacting
components.
The concrete service model defines the following items:
• Binding types. A binding type identifies the type of protocol to which the service is being "bound".
• Endpoints. An endpoint designates the communications endpoint information needed by a service
consumer to interact with a service provider, using a particular protocol. In JBI endpoints are pro forma; the
only protocol used internally is the standard Java-based JBI messaging contracts, which do not involve the
use of normal communications protocols at all. An endpoint definition includes the following items that are
of interest to JBI:
• Endpoint name. This is a simple name, used to designate the endpoint within its service.
• Binding type. This associates a binding type with an endpoint.
• Service. A service is a collection of endpoints that offer access to the same service. A service "implements"
a particular service type (interface). A service has the following items:
• Service name. A qualified name used to indicate the particular service implementation.
• Service type name. The name of the interface implemented by the service.
• Endpoints. The service "contains" one or more endpoints, which are the individual endpoints providing
access to the concrete service.
Note that normally an endpoint is identified by the combination of its service name and its endpoint name. This
combination is referred to as the service endpoint.
4.2 Normalized Message

A normalized message consists of two parts: the abstract XML message as described above, and message
metadata (referred to as message context data). The message context data allows for the association of extra
information with a particular message as it is processed by both plug-in components and system components.
The metadata can affect message processing as the message moves through the JBI environment.

4.3 High-Level Architecture

A top-level view of the JBI architecture is shown in the following figure. The JBI environment exists within a
Figure 4 Top-level view of the JBI architecture
single JVM. External to the JBI environment are service consumers and providers, representing the external
entities that are to be integrated by JBI. These external entities can use a wide variety of technologies to
communicate with Binding Components in the JBI environment. Service Engines are essentially standard
containers for hosting WSDL-defined service providers and service consumers that are internal to the JBI
environment.1
Figure 4 above shows the major architectural components of JBI. This collection of components is called the
JBI Environment. Within each JBI environment, there is a collection of services which will provide operational
support. Key to this set of services is the Normalized Message router (NMR) which provides the mediated
message exchange infrastructure, allowing components to interoperate. In addition, JBI defines a framework
which provides the pluggable infrastructure for adding Service Engines (SEs), and protocol Binding
Components (BCs). These are depicted within the yellow, C-shaped framework polygon.
The right-hand side of the JBI environment depicts the management features of JBI. JBI defines a standard set
of JMX-based controls to allow external administrative tools (shown on the far right) to perform a variety of
system administrative tasks, as well as administer the components themselves.
The core message exchange concept implements WSDL messaging, as discussed above. Service requests are
generated by consumer components, routed by the NMR, and delivered to a provider component. For example,
the BPEL SE may generate a request, which happens to be provided by the external service provider connected
to the WS-I BC. The NMR will route the request to the WS-I binding. The SE in this case is a service consumer,
and the BC a provider.
All provided services are exposed as WSDL-described services (end points, specifically). Services provided by
SEs are described as end points in the same fashion as services provided by BCs (actually by external service
providers). This provides a consistent model of service provision, without regard to location.
1.The term “container” is used in two ways in this specification. A service engine can function as a container
for engine-specific entities, while the JBI environment itself is a container for service engines and binding
components. Because of this, JBI is sometimes called a “container of containers.” The context will make clear
which type of container is being discussed within this specification.

Service consumers may identify needed services by WSDL service name, not by end point address. This
decouples the consumer from the provider, and allows the NMR to select the appropriate provider. Service
consumers may also identify services by resolving Endpoint References. For example, this allows a JBI
component to resolve a service callback Endpoint Reference which was sent in a message.
Aside from the component framework and the NMR, the remainder of the JBI environment provides the
infrastructure for life cycle management, environmental inspection, administration, and reconfiguration. These
provide a predictable environment for reliable operations.
4.4 Normalized Message Exchange

The JBI environment's primary function is to route normalized message exchanges from one component to
another. Messages are delivered in a normalized form.
Binding components must convert “bound” messages (messages in protocol- and transport-specific formats) to
normalized form, as shown below. BCs and SEs interact with the NMR via a DeliveryChannel, which provides
Figure 5 External Service Consumer Message Processing Overview
a bidirectional delivery contract for message reception and delivery.

An external service consumer sends a service request, bound to a particular protocol and transport, to the
binding component. The binding component converts the request to normalized form, as described in a WSDL
model that describes the service exposed by the end point exposed by the BC to the consumer. The BC then
creates a Message Exchange (ME), which is a container for messages involved in various simple message
exchange patterns. It sets ME metadata describing the desired service and operation to be performed. Finally, in
step 2, the BC sends the ME, via its delivery channel, to the NMR for delivery to a service provider.
The NMR selects a suitable service provider, and routes the ME appropriately. The provider must accept (pull)
the ME from the delivery channel.

Reversing the direction, as shown in Figure 6, changes very little to this processing picture, except for what the
binding does. This is depicted below.
Figure 6 External Service Provider Message Processing Overview
A consumer SE/BC creates a normalized message, putting it into a new MessageExchange. The
MessageExchange is addressed by a ServiceEndpoint; the SE does not select which component is used to
perform the service. The ME is sent and accepted in exactly the same fashion as the previous example. After
accepting the ME, the binding denormalizes the message into protocol and transport format, and sends the
message across the wire to the external service provider.
4.5 Management
The JBI environment, including bindings and engines, is administered through JMX. Several management bean
(MBean) types are defined by this specification to create a consistent management environment across the JBI-
provided components and the plug-ins.
Major functions supported by the management interfaces are:
• Installation of engines and bindings (components)
• Life cycle management of components (start/stop controls)
• Deployment of component artifacts to engines and bindings that support dynamic additions to their internal
execution environments. For instance, the SE is an XSLT engine, and the artifacts are new XSLT style
sheets to be installed in the container.
• Monitoring and control.
4.5.1 Component Installation

Engines and bindings must be installed via management interfaces. The verb “install,” as used in this
specification, refers to installation of the binaries and related artifacts to provide the basic functions of the
component. This is distinct from deployment, which is the act of adding application-specific artifacts to the
component to customize its behavior in application-specific ways. For example, an XSLT transformation engine
is installed, while specific transformation style sheets may be deployed to the transformation engine to supply
needed transformation services.

4.5.2 Life Cycle Management

Once an engine or binding is installed, it can be started and stopped using MBean interfaces defined in this
specification. This type of control is referred to as life cycle management.
4.5.3 Service Unit Deployment

As discussed above, deployment refers to the addition of component-specific artifacts to the installed engine or
binding. These artifacts are referred to as Service Units. This specification says nothing about the contents of
service units; they are completely opaque to JBI.
Service units are grouped into an aggregate deployment file called a Service Assembly. This includes a
deployment descriptor that indicates the component into which each SU is to be deployed
4.6 Component Framework

The JBI component framework provides the pluggable interface which allows Bindings and Engines to interact
with the JBI environment. The framework provides the interface to all of the JBI operational services.
The components interface to JBI via two mechanisms: SPIs (service provider interfaces) and APIs (application
program interfaces). SPIs are interfaces implemented by the binding or engine; APIs are interfaces exposed to
bindings or engines by the framework. The contracts between framework and component are detailed in the
“Component Framework” and “Normalized Message Router” sections of this specification. They define the
obligations of both framework and JBI component to achieve particular functional goals within the JBI
environment.
4.7 Normalized Message Router

The normalized message exchange delivery outlined above depends on the Normalized Message Router (NMR)
to route message exchanges between service consumers and providers. The NMR supports performing such
message delivery with varying qualities of service, depending on application needs and the nature of the
messages being delivered.
The qualities of service supplied by the NMR, in collaboration with the bindings and engines as needed, are:
• Best effort. Messages may be dropped, or delivered more than once.
• At least once. Messages may not be dropped, but duplicates may be delivered.
• Once and only once. Messages are guaranteed to be delivered only once.
These are detailed in the “Normalized Message Router” chapter of this specification.
4.8 Components
JBI supports two kinds of components, Service Engines and Binding Components. JBI only distinguishes
between the two kinds through a flag; the model and API are otherwise identical. However, by convention,
Service Engines and Binding Components implement different functionality in JBI. (This distinction is
followed in the JBI-defined management interfaces.)

4.8.1 Service Engines

SEs are the business logic drivers of the JBI system. Engines can orchestrate service consumption and
provision, in the course of, for example, executing long-lived business processes. Other engines can provide
simple services, such as data transformation. Yet other engines may provide sophisticated routing or EDI
services such as message collation / de-collation facilities.
SEs can create new services by aggregating other services. This is a key compositional pattern for languages
such as WS-BPEL, that construct complex processes from services.
SEs can serve as service providers, service consumers, or both.
4.8.2 Binding Components

BCs are used to send and receive messages via particular protocols and transports. They serve to isolate the JBI
environment from the particular protocol by providing normalization and denormalization from and to the
protocol-specific format, allowing the JBI environment to deal only with normalized messages. (Note that
protocol-specific metadata can be attached to a normalized message, or the message exchange, in their
metadata, allowing protocol-specific information to be conveyed to a SE or BC in a fashion that is opaque to
other JBI environment components.)
4.9 Examples
The following examples will help illustrate the use of the pieces of the JBI environment and components to
perform typical integration tasks.
4.9.1 One-way Message Adapter

In this scenario, a JBI environment supplies a simple message adaptation service for a one-way message. A
message is sent to the JBI environment, transformed, then sent to a destination outside of the environment. This
is a simple form of point-to-point, A2A integration, and is illustrated below.
Figure 7 Example One-way Message Adapter Application Message Sequence Diagram

Note that the double-headed arrows in the sequence chart indicate messages routed by the NMR. This is an
important feature: the components involved are loosely coupled. Each component indicates to the NMR the
desired message destination only by service name; the NMR determines which component this corresponds to.
Client1 is a service consumer that wishes to make a one-way request of a service offered by Service1.
Unfortunately, Client1 and Service1 don't have a common message format or messaging protocol, thus
necessitating the use of integration middleware to adapt both the message format and the messaging protocol
suitably. The middleware in this case is a JBI environment, shown in the large, rounded rectangle in the middle
of the message sequence chart. The individual objects shown are:
• BC1. A binding component that “speaks” Client1's protocol, which happens to be WS-I BP 1.1 compliant
SOAP.
• SE1. A service engine used to provide light-weight sequencing of services. This can be configured to
perform the desired message adaptation and forwarding.
• SE2. A service engine used to transform messages using XSLT 1.0.
• BC2. A binding component that “speaks” Service1's protocol, which is (in this example) AS2 over HTTP.
The message exchanges in the message sequence chart, above, are described in detail below.
• Client1 to BC1. The client is configured to send its request of Service1, the payload of which we term
REQ1, to BC1. As far as Client1 is concerned, BC1 is the end point for accessing Service1, using the
client's own messaging protocol.
• BC1 normalizes and forwards the inbound request for Service1, using the NMR to route the message. The
JBI instance is configured to send requests for Service1 to SE1. (SE1 is a light-weight engine that can
sequence the conversion and forwarding of messages.)
• SE1 selects the type of conversion to be performed, and sends a request to the conversion service to have
REQ1 converted to what we will label REQ1A. The NMR will route this message to the SE2, which
provides the desired service.SE2 will perform the transformation and synchronously return the result SE1.
• SE1 completes the sequencing the conversion-and-forward process by sending the result of the
transformation, REQ1A to Service1. (The NMR will route this to BC2).
• BC2 denormalizes the message, and sends it (one-way) to Service1.


CHAPTER 5
Normalized Message Router
The normalized message router, or NMR, receives message exchanges from JBI components (engines or
bindings), and routes them to the appropriate component for processing. This mediated message-exchange
processing model decouples service consumers from providers, and allows the NMR to perform additional
processing during the lifetime of the message exchange.
Note that this chapter makes use of WSDL 2.0 terms, rather than the older WSDL 1.1 ones.
5.1 Key Concepts

This section introduces key concepts in the NMR architecture. The goal of the NMR is to allow components
acting as service producers and consumers to interoperate with one another in a predictable fashion, using
WSDL-based service descriptions as the sole source of coupling between them. This is key to allowing mix-
and-match assembly of components, creating the basis of integration solutions and a services infrastructure.
WSDL [WSDL 2.0, WSDL 1.1] provides the basic model, and description mechanism, for interaction of JBI
components. WSDL provides an abstract service model, based on operations which are defined as XML
message exchanges. This abstract model can be extended to provide binding-specific information: protocol-
specific information declaring how the abstract model is mapped to an actual communications protocol and
endpoint [WSDL 2.0 bindings].
JBI makes extensive use of WSDL’s abstract message model. The NMR can be thought of as an abstract
WSDL-defined messaging system infrastructure, where bindings and engines serve to provide and consume
WSDL-defined services.
WSDL defines an operation as an exchange of messages, between consumer and provider, done according to a
message exchange pattern that is understood by both participants. A collection of related operations is called an
interface (formerly portType in WSDL 1.1). A service implements such an interface. A service has one or more
endpoints, which provide access to the service over a specific binding (protocol).
All of these WSDL concepts are used to structure how services are modelled in the APIs and SPIs of JBI.
5.1.1 Service Consumers and Providers

JBI engines and bindings function as service consumers, providers, or both. A service provider makes a WSDL-
described service available through an endpoint. A consumer makes use of services by initiating message
exchanges that invoke particular operations. A service “implements” a WSDL interface, which is a collection
of related operations described by the exchange of abstractly defined messages.

Consumers and providers are decoupled, in that they normally share only the (abstract) service definition, and
not endpoint information. This isolates the consumer from the particulars of the service provider's
implementation (protocol etc.).
A WSDL interface can be implemented by more than one service. A consumer looking for providers of an
interface may find more than one provider (service and associated endpoint).
5.1.2 Normalized Message

JBI uses the concept of a “normalized” message for interaction between consumers and providers. A
normalized message consists of three main parts:
• The “payload”, or bare message: an XML document that conforms to an abstract WSDL message type,
without any protocol encoding or formatting. (This is not a canonical form for the message.)
• Message properties (sometime called metadata). These hold extra data associated with the message, gained
during the processing of the message. Such properties can include security information (security principal
for digital signers of received messages, for example), transaction context information, and component-
specific information.
• Message attachments. A portion of the content of the “payload” (content) of the message can be made up of
attachments, referenced by the payload, and contained within a data handler that is used to manipulate that
contents of the attachment itself. Such attachments can be non-XML data.
The normalized message provides interoperability between components, using abstract WSDL message type
definitions.
5.1.3 Delivery Channel

A DeliveryChannel represents a bidirectional communication pipe used by bindings and engines to
communicate with the NMR. The DeliveryChannel forms the API contract between service consumers,
providers and the NMR. A service consumer uses its delivery channel to initiate service invocations, while a
service provider uses its delivery channel to receive such invocations. A component that functions as both
consumer and provider uses the same delivery channel for both roles.
Take, for example, a binding that receives requests from a service consumer that is external to the JBI
environment. Upon receiving such an inbound service invocation request, the BC must act as a service
consumer while interacting with the NMR via its delivery channel. (This reflects the binding component's
function as a form of consumer proxy in this use case.)
Each component is provided with a single delivery channel. Therefore implementations of
DeliveryChannel MUST support concurrent use of a given channel from multiple threads.
5.1.4 Run-time Endpoint Activation

Run-time activation is the process by which a service provider activates the actual services it provides, making
them known to the NMR so that the NMR may route service invocations to that service. Activation is divided
into two steps:
• Declaring a service endpoint to the NMR.
• Providing metadata describing the nature of an endpoint definition.
Declaration is the process by which a binding or engine activates an endpoint name with the NMR. Any
endpoint name declared within the NMR must be supported by metadata describing the details of the
registration. Such details are provided separately, using a SPI that is part of the Component interface.

5.1.5 Service Invocation and Message Exchange Patterns

Service invocation refers to an instance of an end-to-end interaction between a service consumer and a service
provider. While it is impossible to define a complete set of service invocation patterns within JBI, the following
list represents the directly supported interactions which must be supported by JBI implementations:
• One-Way: consumer issues a request to provider with no error (fault) path provided.
• Reliable One-Way: consumer issues a request to provider. Provider may respond with a fault if it fails to
process request.
• Request-Response: consumer issues a request to provider, with expectation of response. Provider may
respond with a fault if it fails to process request.
• Request Optional-Response: consumer issues a request to provider, which may result in a response.
Consumer and provider both have the option of generating a fault in response to a message received during
the interaction.
The consumer and provider roles described above may be performed by bindings or engines, in any
combination of the two. When a binding acts as a service consumer, an external consumer is implied. Similarly,
when the binding acts as a provider, an external service is implied. The use of a service engine in either role
implies a local actor for that role.
WSDL 2.0 Predefined Extensions [WSDL 2.0 Extensions] defines a message exchange pattern (MEP) as “the
sequence and cardinality of abstract messages listed in an operation.” JBI uses this concept to define
interactions between two nodes: the consumer node, and the provider node. The pattern is defined in terms of
message type (normal or fault), and message direction.
MEPs always reflect the provider's point of view. For example, in a request-response interaction, the MEP is in-
out, which reflects the flow of messages as seen by the provider. From the consumer's perspective, the direction
of message flow is reversed, but the MEP used by the NMR in its interactions with the consumer will always
reflect the provider’s perspective. This is a conventional practice when dealing with WSDL MEPs. The in-out
pattern is illustrated below, in Figure 8.
Figure 8 In-out Message Exchange Patterns
The first message (a request) is sent from the consumer to the provider (thus it has the “in” direction, from the
point of view of the provider). The second message (a response) is sent from the provider to the consumer (thus
is has the “out” direction). These exchanges are performed in the sequence given, with single messages. From
the provider’s perspective the exchange is a “in” message, following by an “out” message, thus leading to the
name of the pattern.

5.1.6 Message Exchange

A Message Exchange (ME) serves as a “container” for the normalized messages that are part of a service
invocation. It encapsulates not only the normalized messages that are represented by the in and out messages of
the message exchange pattern realized by the ME, but holds metadata and state information associated with the
on-going exchange. A Message Exchange represents the JBI-local portion of a service invocation. The
following table shows the relationship between service invocations and message exchange patterns.
Service Invocation Message Exchange Pattern (Provider View)

One-Way In-Only
Reliable One-Way Robust In-Only
Request-Response In-Out
Request Optional-Response In Optional-Out
Table 2 Service Invocation to MEP Mapping
The activity diagram in Figure 9 depicts a one-way service invocation between two local Service Engines,
including a message exchange instance: 1
Figure 9 One-way Service Invocation Between two Service Engines
SE1, acting as a service consumer, invokes the desired service and operation by creating and initializing an in-
only message exchange, containing the request message. SE1 then sends the message exchange instance to the
NMR. This is indicated by the object flow between the SE1 and NMR swim lanes.
The NMR determines which service provider should provide the requested service and operation, and routes the
message exchange instance for delivery to the provider. This is shown by the object flow between the NMR and
SE2 swim lanes.
Note that this diagram is not meant to imply that the invoker must block a thread of execution to await the
completion of the exchange. The invoker can be event-driven, where sending and receiving message exchanges,
as shown in the activity diagram, advances the engine’s internal state without necessarily tying up thread
resources.
1.Note that this depicts a successful service invocation, so it applies to both the reliable and normal one-
way invocation types.

The following depicts a reliable one-way invocation between service engines hosted in separate JBI
environments. Note that there is no provision for “federating” separate JBI instances; the two JBI instances
Figure 10 SE Invokes Service Provided by Remote JBI Instance: Robust In with Fault
shown in this example see each other as remote consumers and providers, accessed by the communications
protocol provided by BC1 and BC2. There is no special relationship between the two JBI instances that affects
how service invocation is performed between them.
SE1 constructs and initializes a robust-in message exchange instance, and sends it to the NMR. (In the process
of creating the ME instance, the NMR has assigned it the unique identifier 'X'.) The NMR determines which
service provider should be used, and sends the message exchange to BC1 as a robust-in patterned instance. BC1
packages the request according to the requirements of the protocol that it implements, and sends the request to
the service provider, which, in this example, happens to be another JBI instance, JBI2, and is accessed via an
endpoint exposed by BC2.
When BC2 of JBI2 receives the request, it constructs a robust-in-patterned message exchange instance (“Y”),
and sends it to the NMR. The NMR of JBI2 determines which service provider should be used, and sends the
message exchange instance (“Y”) to SE2.
SE 2 then receives instance “Y”. After processing the request, SE2 may elect to return a fault message,
indicating an application-level error. In this case, SE2 can use instance “Y” to return a fault message, which will
follow the reverse of the path the request followed, eventually arriving at SE1 of JBI1, in message exchange
instance “X”. (A positive “done” response in such a MEP would follow the same path, but is not shown here for
sake of clarity.)

The following depicts a request-response invocation between a JBI-hosted Service Engine and a remote service
provider.
Figure 11 SE Invokes Remote Service
The service engine SE creates and initializes an in-out-patterned message exchange instance. SE sends this to
the NMR, which determines which service provider should process this invocation. In this case binding BC is
selected. When BC receives the message exchange (an in-out pattern), it denormalizes the request, and sends it
using its communications protocol to the external provider. The provider processes the request, returning either
the normal response or an application-level fault, as appropriate. The BC normalizes the response, and adds it to
the message exchange. The message exchange is then sent to the NMR, which routes it back to the consumer,
SE.
5.1.7 Endpoints
Endpoints, in WSDL 2.0, refer to a particular address, accessible by a particular protocol, used to access a
particular service. JBI uses this concept, referring to two distinct types of endpoints:
• External. Endpoints outside of the JBI environment:
• Endpoints exposed by external service providers.
• External endpoints exposed by binding components, for the use of external service consumers.
• Internal. Endpoints exposed by service providers within the JBI environment. These are accessed using the
NMR APIs.
Binding components serve to map between internal endpoints and external. For example, an internal endpoint
provided by a binding component is mapped by the BC to an external service provider endpoint.
In JBI endpoints are referred to (or addressed) in three distinct ways:
• Implicitly. JBI selects the endpoint of a service provider based on service type.
• Explicitly. A consumer chooses the endpoint of a service provider based on its own logic or configuration.
• Dynamically. An endpoint reference (EPR) is used within a message exchange to provide a “call back”
address that the service provider should use to send further message exchanges related to the on-going

application-level conversation. EPRs are used in two distinct ways in JBI:

• EPR creation. A component that wishes to provide a “call back” address in a message must be able to
create a suitable EPR.
• EPR resolution. A component that receives an EPR must resolve it (i.e., convert it into a usable
endpoint) in order to send message exchanges to the appropriate endpoint (typically an external service
provider).
5.2 Elements of a Message Exchange

• Pattern – every message exchange is described by a pattern, which describes the direction, sequence,
cardinality, and names of messages (normal or fault) which constitute in the exchange.
• Initiator – component which creates the message exchange. Service consumers act as initiators in all
standard JBI-defined message exchange patterns are consumer initiated.
• Servicer – component which services the message exchange. Service providers act as servicers.
• Role – the role a component plays when it “owns” a message exchange instance:
• Provider – the component that provides the service requested by a message exchange.
• Consumer – the component that requests a service from a provider.
• Address – a service reference, endpoint reference, and operation name for the logical address which the
NMR uses to route message exchanges.
• Message – a message exchange carries one or more messages.
• Fault – a message exchange may carry at most one fault. A fault is a special kind of message.
• Status – describes the status of the message exchange: error, done, or active.
• Error – A Java Exception object used to describe the nature/source of an error status.
• Properties – initiators and servicers of a message exchange may associate arbitrary properties with a
message exchange. The NMR may choose to reserve certain property names to declare QoS, security,
transaction, or other operational metadata.
Message exchange instances are short-lived, and will not survive a system shutdown or failure. Higher level
error recovery logic, provided by consumer and provider components, must handle such error cases. Durable
message exchange instances, which would allow JBI to supply recoverability, are being considered for JBI 2.0.
5.2.1 Exchange Summary

The following message exchange patterns are defined by WSDL 2.0, and utilized by JBI. Each definition
includes a fault rule, which specifies which message in the exchange is created (or replaced) to convey a fault
from one participant to the other. The equivalent WSDL 1.1 operations, where applicable, are also listed.
Pattern Name Message Sequence Fault Rule WSDL 1.1 Operation

In-Only in none One-way
Robust In-Only in on in -
In-Out in, out replaces out Request-response
In Optional-Out in, out on in or out -
Table 3 JBI Standard Message Exchange Patterns (from WSDL 2.0)

5.3 Normalized Message

Normalized messages are the messages of a JBI message exchange. This section defines normalized messages,
and discusses the processing model JBI presents for such messages.
5.3.1 Normalization Defined

Message normalization is the process of storing protocol and business context in a generic, transportable
fashion. All messages handled by the Normalized Message Router are in normalized form. Normalization is a
two-way street:
• Normalizing a message consists of mapping context-specific data to a context-neutral abstraction.
Essentially, a normalizer must 'translate' context information that needs to be interpreted by the NMR into a
'generic' form that the NMR understands. Any other information (e.g. payloads, additional relevant context)
can be added to a message, and carried by the NMR, but these data are completely opaque to the NMR.
Note that normalization does not imply canonicalization of the payload data.
• Denormalizing a message refers to the process of receiving a message from the NMR and translating it
back into a context-specific representation. Denormalization represents the inverse of a normalization
operation. For example a SOAP binding would denormalize a message by placing appropriate parts of the
message and its metadata into a SOAP envelope, applying the required encoding style as it does so.
5.3.2 Structure of a Normalized Message

There are two distinct parts of a Normalized Message: context and content.
• Message context refers to a set of message “properties”, which may be used to associate metadata with a
message.
• Message content is essentially a generic source abstraction which contains all of the message data. In this
context, the term “contain” is defined as inclusion within the abstract data model describing the message.
5.3.3 Processing Methods

The Normalized Message abstraction does not prescribe a specific processing style for the message content. A
consumer of message content is free to choose the processing method based on context-specific requirements.
For example, a high performance binding component may wish to stream the content using a pull parser or a
raw byte stream. A transformation service engine, on the other hand, may require that the entire message be in
memory to facilitate arbitrary content queries, in which case an XML DOM tree representation may be
appropriate.
5.3.4 Binary Inclusion

The primary content of a normalized message is always XML; non-XML (including binary) attachments to the
primary content are supported through use of the Java Activation Framework, and normalized message
attachments.
5.3.5 Support for WSDL 1.1

Service providers may describe themselves using WSDL 1.1, rather than WSDL 2.0. Since WSDL 1.1’s
message model is quite different from that of 2.0, JBI defines a mapping from WSDL 1.1-defined messages to
the normalized message form of a single XML document.

5.4 NMR Design

This section provides detailed design information on the Normalized Message Router. The contracts between a
JBI component (binding or engine) and the NMR are detailed.
5.4.1 Activation
As stated previously, activation is the process by which service providers declare to the NMR the particular
services they provide. Each declaration must be accompanied by a corresponding metadata definition, which
describes the declaration. (These metadata are supplied by a Component-supplied SPI.) JBI requires that
WSDL 1.1 or WSDL 2.0 be used for all such declarations. The NMR presumes (but does not enforce) that all
such declarations are compliant with the WSDL specifications. However, if the metadata are malformed, it is a
likely consequence that service consumers will be unable to properly invoke the service.
5.4.1.1 Service Provider Activation
A domain model for service provider activation is pictured below. Each endpoint activated by a provider MUST
Figure 12 Service Activation Domain Model
be accompanied by metadata describing the service, endpoint, and binding details for the endpoint. (A service
engine uses a special JBI-defined binding type for service engine-provided services being so activated.)

A logical sequence diagram depicting a activation scenario follows. This picture is limited purely to activation-
Figure 13 BC Endpoint Activation Message Sequence Chart
related activity, and does not address the relation between endpoint activation and message exchanges.
1. As a precondition, the BC provides an implementation of the Component SPI, part of which is used to
provide metadata describing activated endpoints. (All components MUST provide this.)
2. BC activates an endpoint name.
3. NMR initializes the Service Endpoint.
4. SE queries the NMR for endpoint by name (or some other criteria).
5. SE uses the endpoint to query NMR for metadata describing the Service Endpoint.
6. NMR invokes the BCs Component SPI to fetch the appropriate metadata.
7. SE parses the DOM document returned by the NMR.
5.4.2 Exchanging Messages

This section provides an in-depth discussion of the four standard MEPs supported in JBI. It is important to note
that the NMR provides for an extensible model of message exchange. JBI vendors that wish to extend the
standard catalogue of four MEPs are free to do so.
Each pattern ends with a status exchange; this is necessary to deterministically complete the exchange. This is
especially useful when optional messages (or faults) are part of the exchange pattern, but is necessary in all
MEPs to support reliable message exchange.

Exchange patterns begin with the initiator, which in the standard JBI patterns, is always the consumer, which
creates and initializes a new exchange instance. The consumer “owns” the message exchange instance until it
sends it for delivery (using DeliveryChannel.send()). Subsequently the participants alternate between
accepting the message exchange instance and sending it, until one participant sets the exchange status to a
terminal state, and sends it back to the other participant. A component “owns” a message exchange when it
accepts it (using DeliveryChannel.accept()).
The following diagrams depict the possible interactions between the consumer and provider for each type of
standard JBI message exchange pattern. Each pattern is a contract between the two participants, in their role as
service provider or consumer. Note that a participant can be easily determine its role when accepting a message
exchange instance by using MessageExchange.getRole(). This is helpful for participants in more
complex patterns, as well as a convenience for participants in simpler patterns.
5.4.2.1 Diagram Key
The MEP diagrams shown here use the symbols displayed in the following figure. The diagrams themselves
present a chronological view of the exchanges, with time progressing from the top of each diagram to the
bottom. Alternatives (fault versus normal response) are shown using the choice symbol.
Figure 14 MEP Diagram Key
5.4.2.2 In-Only Message Exchange

This pattern is used for one-way exchanges.
Figure 15 In-only Message Exchange Pattern
Notes:
• Consumer initiates with message.
• Provider responds with status to complete exchange.

5.4.2.3 Robust In-Only Message Exchange

This pattern is used for reliable, one-way message exchanges.
Figure 16 Robust In-only Message Exchange Pattern
Notes:
• Provider may respond with status or fault.
• If provider response is status, the exchange is complete.
• If provider response is fault, consumer responds with status to complete exchange.
5.4.2.4 In-Out Message Exchange
This pattern is used for two-way exchanges.
Figure 17 In-out Message Exchange Pattern
Notes:


• Provider responds with message or fault.
• Consumer responds with status.
5.4.2.5 In Optional-Out Message Exchange
This pattern is used for a two-way exchange where the provider's response is optional.
Figure 18 In Optional-out Message Exchange Pattern
Notes:
• Provider may respond with message, fault, or status.
• If provider responds with status, the exchange is complete.
• If provider responds with fault, consumer must respond with status.
• If provider responds with message, consumer may respond with fault or status.
• If consumer responds with fault, provider must respond with status to complete exchange.
5.4.3 Routing Message Exchanges

A new message exchange instance, created by a consumer using a MessageExchangeFactory, is
initialized by the consumer with the following possible information about the provider desired, in order of
increasing specificity: interface name, service name, endpoint name. Each address type is discussed in detail
below. If multiple address types are provided in the message exchange instance, the implementation MUST use
the most specific address supplied, and ignore the others.

• Interface name. If this is specified on a message exchange, the implementation MUST use implicit
endpoint selection.
• Service name. The implementation MUST choose a provider endpoint that belongs to the given service
name, using implicit endpoint selection.
• Endpoint. The implementation MUST use the given endpoint as the service provider, either directly or
indirectly (see section 5.4.3.3 for details on direct and indirect routing).
If the implementation determines that more than one endpoint can be used to provide the service specified by
the message exchange (which is possible when using interface or service names to address the exchange), the
implementation MUST choose one provider endpoint. How this selection is accomplished is not specified here.
When a message exchange is routed from the service provider, it MUST always be sent to the component that
originated the exchange. Subsequent sending of the exchange from the consumer to provider MUST always
send the exchange to the provider endpoint selected during the initial send of the exchange.
When a message exchange is sent to a particular provider endpoint, the implementation MUST deliver the
message exchange to the DeliveryChannel of the component that activated the given endpoint.
When a message exchange is returned to a consumer component, the implementation MUST deliver the
message exchange to the DeliveryChannel of the consumer component.
5.4.3.1 Implementation Changes to Message Exchange Address Properties
A consumer may choose to set several message exchange provider address properties in the course of
initializing the exchange instance, and before sending it. When one provider address property is set, the
implementation MUST NOT alter any of the others (interface name, service name, or service endpoint).
When the component sends the new exchange instance, the implementation MUST set the endpoint property of
the exchange instance to the endpoint selected by the NMR as service provider (if not specified by the
component). Note that if the component specifies the endpoint directly, the implementation MUST NOT alter
this value, even if the endpoint refers to a service connection, as detailed in section 5.4.3.3.
5.4.3.2 Implicit Endpoint Selection Process
When the consumer specifies the desired service provider with any form of address other than a service
endpoint, the JBI implementation MUST select the provider endpoint implicitly. The process that
implementations MUST follow while performing implicit endpoint selection is given in this section. The
implicit endpoint selection process MUST be performed when the new message exchange instance is sent for
delivery by the consumer, when it calls DeliveryChannel.send or DeliveryChannel.sendSync.
If there are no candidate service provider endpoints that match the given service address, or if no suitable
matches are found of candidate providers during the execution of this selection process, the send or
sendSync method MUST throw a MessagingException with a suitable error message detailing the
routing failure.
For each candidate provider endpoint being considered by the JBI implementation, it MUST do the following:
• call the consumer’s Component.isExchangeWithProviderOkay() method, providing the
candidate endpoint and the message exchange that is the subject of this selection process as parameters.
• call the provider’s Component.isExchangeWithConsumerOkay() method, providing the candidate
endpoint and the message exchange that is the subject of this selection process as parameters.
A candidate provider endpoint that causes both of the above calls to return true is considered a match, and
suitable for use as an implicitly selected provider endpoint. Implementations MUST select one provider
endpoint to serve as the result of this selection process from all matching provider endpoints found, using
implementation-specific means. An implementation MAY “short circuit” this process by selecting the first
matching provider endpoint found.

5.4.3.3 Message Exchange Routing and Service Connections

As detailed in the “Management” chapter, service assemblies may contain deployment-provided routing
information, called service connections and service link types. Service connections provide explicit mappings
from a consumer-provided address to the actual provider service endpoint. Service link types provide extra
information about a component’s expectations, as a service consumer, concerning the use of service connections
to influence routing decisions made by the JBI implementation.
Service connections are defined logically as structures that contain the following properties:
• A consumer address. This is an address that will be provided by a service consumer. This can take one of
two forms:
• Service type name. The consumer specifies the desired service type, using its interface name.
• Service endpoint name. The consumer specifies the desired service endpoint, using its fully qualified
name (service QName and endpoint name).
• A provider endpoint address. This is the address of the actual provider to route exchanges sent to the
consumer address. This can be an internal endpoint or a resolved endpoint reference (EPR).
Each consumer MAY declare, in service unit metadata, its expectations concerning how service connections are
to be applied to it when it consumes a particular service. This is termed provider linking. There are three types
of provider linking possible, which only apply when the consumer address is a service endpoint name:
• Standard links. The NMR performs its normal routing, including application of service connections.
• Hard links. The consumer always specifies the endpoint of a provider directly, and the routing should not
be affected by service connections. In other words, the consumer is asserting that the endpoint address
given must exist as an internal endpoint.
• Soft links. The consumer always specifies the endpoint of a provider using an indirect address. In this case
the consumer provides a “false” (non-existent) endpoint. This type of link is an assertion by the consumer
that the address given must be resolved using a service connection, and that it is an error if the named
endpoint exists as an internal endpoint.
Link types are declared by service units, in their deployment descriptors, as described in the “Management”
chapter. JBI implementations must mark message exchanges, in an implementation-determined way, with the
link type applicable to the service invocation when the component sends the new message exchange instance to
the delivery channel.
If a new message exchange specifies an endpoint, the following actions MUST be performed by the JBI
implementation when DeliveryChannel.send is called.
• if the endpoint specifies an internal endpoint, and the link type is either “standard” or “hard”, then route the
exchange instance to the given endpoint;
• otherwise, if the endpoint specifies a service connection’s consumer endpoint, and the link type is either
“standard” or “soft”, then route the exchange instance to the provider endpoint given in the service
connection;
• otherwise throw a MessagingException, indicating, in its message, the failure type:
• internal endpoint address specified when soft link required, or
• service connection address specified when hard link required.
Note that the implementation MUST use only the service connections that are associated with currently running
service assemblies.

The implementation MUST apply service connection processing to endpoints selected when implicit endpoint
selection is used (i.e., a service type or name is specified, rather than an endpoint).
5.4.4 Use of Dynamic Endpoint References

The dynamic endpoint reference (EPR) is defined in section 5.1.7, above. Resolution of received EPRs is
ultimately the responsibility of binding components, since EPRs contain binding-specific information. Creation
of EPRs is the responsibility of bindings, for similar reasons.
EPRs use specialized XML vocabularies, which are typically binding-specific. Components that are either
resolving a received or creating a new EPR (typically service engines) SHOULD NOT be required to
“understand” the EPR vocabulary, but are not, in this processing model, banned from doing so. Creating
specialized EPR handling inside service engines is, in general, a poor practice, since it creates coupling between
the engine and a particular protocol, limiting system configurability.
EPRs can be created for internal endpoints. There are two types of internal endpoints, which MUST be handled
differently by the JBI implementation:
• Service Engine-provided Endpoint. An EPR for such an endpoint MUST use the JBI-defined EPR
vocabulary for providing such references (see section 5.5.4.1).
• Binding Component-provided Internal Endpoint. An EPR for such an endpoint SHOULD refer to the
external provider endpoint, if possible, otherwise such an EPR SHOULD use the JBI-defined EPR
vocabulary.
EPRs can be created for external endpoints. As noted above, an internal (binding) endpoint that serves as a
proxy for an external service should, if possible, refer directly to the external provider’s endpoint.
For external endpoints exposed by a binding component (for use by external consumers), components will need
to create EPRs referring to such endpoints. Such external endpoints can be discovered by other components
using special query methods. Such external endpoints are created and registered by the binding component for
this purpose.
5.4.4.1 Binding-implemented Endpoints
Binding components are required to provide their own implementations of the ServiceEndpoint interface
in two EPR-related use cases:
• External endpoint. In this case, the binding is registering an external endpoint that it was responsible for
creating (it is accessed by external service consumers). The external endpoint functions as a proxy allowing
external consumers to use an internal service. The binding-supplied ServiceEndpoint implementation
for external endpoints MUST behave as follows:
• getInterfaces() MUST return an array of interface QNames that the endpoint implements.
• getServiceName() MUST return the same service name as the internal provider.
• getEndpointName() MUST return a legal endpoint name, which must be distinct from the internal
provider endpoint name.
• getAsReference() MUST return an endpoint reference that external consumers, capable of
communicating with the binding component, can use to send requests to the binding.
External endpoints are registered with the sole purpose of providing endpoint references to those endpoints.
They cannot be used to address message exchange instances. The DeliveryChannel.send methods
MUST throw an exception if a component addresses a message exchange instance with an external endpoint.
• Internal endpoint. In this case, the binding is resolving an endpoint reference; the endpoint created by the
binding MUST resolve to the service endpoint indicated by the EPR. This type of endpoint can be used to
address a message exchange instance. The binding’s ServiceEndpoint implementation MUST behave

as follows:
• getServiceName() and getEndpointName() MUST return an appropriate, fully-qualified
service name that is unique for the external endpoint to which the EPR referred. In this context,
appropriate means one of the following:
• The service name provided as part of the resolved EPR, or, if that is not applicable
• a service name that is unique to the binding component.
• getAsReference() MUST return null. If an EPR is needed for the endpoint, the original EPR must
be used.
JBI implementations MUST ensure that message exchanges that are addressed to an internal endpoint created
by EPR resolution are delivered to the component that created that internal endpoint. Component
implementations MUST distinguish between JBI-supplied ServiceEndpoints and ones created by itself.
An example endpoint implementation is shown in the listing below.
class MyServiceEndpoint implements ServiceEndpoint {

private DocumentFragment epr_;
private QName serviceName_;
private String endpointName_;
private QName interfaceName_;
MyServiceEndpoint(DocumentFragment epr) {
epr_ = epr;
// a real binding component would pick apart the EPR, and
// determine appropriate service description items. This
// binding just makes up a fake description for the
// dynamic endpoint.
serviceName_ = new QName("http://www.example.com/services",
"service1");
endpointName_ = "endpoint1";
interfaceName_ = new QName("http://www/example.com/interfaces",
"interface1");
}
public QName getServiceName() {
return serviceName_;
}
public String getEndpointName() {
return endpointName_;
}
public DocumentFragment getAsReference(QName operation) {
return epr_;
}
public QName[] getInterfaces() {
return new QName[] { interfaceName_ };
}
}
Listing 2 Example Binding Implementation of a Dynamic Service Endpoint
5.5 NMR API

The NMR exposes a standard API to SEs and BCs.
5.5.1 Message API

The Message API defines the content and behavior of normalized messages within JBI. Key functions of this
API include:
• Storing/retrieving content using a standard data model (XML)

• Ability to set/get context information on a per-message basis (properties)
Figure 19 Message API Class Diagram

5.5.1.1 Normalized Message

A normalized message consists of the following:
• The XML “payload” document, as defined in the abstract message definition. This is the content of the
normalized message.
• Message properties (or metadata), associated with the message itself. Some properties are JBI-defined,
while others can be defined by components.
• Binary attachments to the message.
5.5.1.1.1 Normalized Message Content
The normalized message content (or payload) is an XML document, defined in the service description (typically
using XML Schema 1.0). In order to provide flexibility in processing XML, the normalized message uses the
the TRaX Source interface from the JAX-P API. This is depicted in Figure 19, above, in the
javax.xml.transform package.
The normalized message content MUST conform to the abstract message definition schema given in service
description supplied by the service provider.
The producer of a normalized message MUST use the NormalizedMessage.setContent() method to
set the appropriate XML Source needed to access the content of the payload document. Consumers of a
normalized message SHOULD use the NormalizedMessage.getContent() method, and consume the
content as required.
5.5.1.1.2 Normalized Message Attachments
An attachment to a message is represented using a Java Activation Framework DataHandler. The
NormalizedMessage interface contains methods to add, remove, and list attachments associated with the
message. A message may contain any number of attachments.
The producer of a NormalizedMessage with attachments is responsible for mapping the content of a native
message to the normalized form with attachments. The consumer of a NormalizedMessage is responsible
for parsing the XML body of the message and processing attachments referenced therein. The producer and
consumer rely on the WSDL definition of the message to determine the enveloping structure of the normalized
message content.
WS-I Attachments Profile 1.0 (AP) [WS-I AP] and XML-binary Optimized Packaging (XOP) [W3C XOP] are
two web services standards in this area. Processing rules for using these standards to reference attachments
within the XML body of the normalized message content are given it the next subsections.
5.5.1.1.2.1 Processing Rules for WS-I Attachments Profile 1.0
• Each attachment MUST be referenced by a swaRef element/attribute in the XML body of the message
content.
• The cid: specified in the swaRef element/attribute MUST match the id of the DataHandler
encapsulating the attachment content.
See [WS-I AP] for further details on using SOAP with attachments.
5.5.1.1.2.2 Processing Rules for W3C XML-binary Optimized Packaging (XOP)
• Each attachment MUST be referenced by a xop:Include element in the XML body of the message
content.
• The href attribute value specified in a xop:Include element MUST match the id of the
DataHandler encapsulating the attachment content.
See [W3C XOP] for further details on using XOP.

5.5.1.1.3 Normalized Message Properties

The following table summarizes the standard properties that this specification defines for normalized messages.
Name Type/Value Description

javax.jbi.security.subject javax.security.auth.Subject JAAS security subject responsible who
signed the message, or that will be needed to
sign the message
javax.jbi.messaging.protocol.type java.lang.String The protocol type name (using the same
values as the WSDL 2.0 binding type
attribute) of the binding that created the
message
javax.jbi.messaging.protocol.headers java.util.Map A set of name/value pairs specific to the
protocol used by the binding. The names
must be Strings; the values are of a binding-
defined type. (For SOAP headers, these
values are org.w3c.dom.DocumentFragment
nodes).
Table 4 Standard Normalized Message Properties
Note that the javax.jbi.messaging.protocol.type and javax.jbi.messaging.protocol.headers properties are set by

binding components. These values are typically used only by the binding component itself, since they are
binding-specific. Other components may use these properties, however, this is a poor practice, since it can bind
the component to a particular protocol.
5.5.1.1.4 WSDL 1.1-Defined Content Messages
WSDL 1.1 defines abstract messages in terms of message parts, which are in turn described using a schema
language, typically XML Schema. This differs markedly from WSDL 2.0 and the normalized message model
used by JBI. In order to allow components that provide services defined using WSDL 1.1 to interoperate with
consumers, JBI defines an XML document format for “wrapping” WSDL 1.1 message parts. This allows both
consumer and provider to interact using this well-known mapping to a “wrapped doc-literal” form of the
message that is used for normalized message content.
A wrapped literal document must conform to the schema given in the listing below.
default namespace jbi = "http://java.sun.com/xml/ns/jbi/wsdl-11-wrapper"

start =
element message {
attribute version { xsd:decimal },
attribute type { xsd:QName },
attribute name { xsd:nmtoken }?,
part*
}
part =
element part {
# part value
( (element* { text }) | text)
}
Listing 3 Normalized Message Context Schema for Wrapper Document for WSDL 1.1-defined Messages
This wrapper MUST be used for messages within portType (abstract) operations (wsdl:input, wsdl:output, or
wsdl:fault). The document element <jbi:message> is the wrapper for all parts for such messages. It has the
following attributes and elements:
• version attribute, which must be 1.0.

• type attribute, which is the qualified-name of the WSDL 1.1 message definition contained in the wrapper.
This corresponds to the wsdl:input, wsdl:output, or wsdl:fault message attribute value.
• name attribute, which corresponds to the optional name attribute of the wsdl:input, wsdl:output, or
wsdl:fault corresponding to the normalized message. If this attribute is not provided, the WSDL 1.1 default
naming rules apply.
• zero or more <jbi:part> elements, representing the logical parts of the WSDL 1.1-described message.
All logical parts of the message must appear here, in the same order as defined in the WSDL 1.1 message
description referred to by the type attribute.
Each <jbi:part> element MUST contain the value of the logical part of the WSDL 1.1-defined message.
The <jbi:part> element may contain XML elements or non-XML text.
After conversion to wrapped doc-literal form, the normalized message content for a WSDL 1.1-defined
message MUST also conform to the requirements stated for WSDL 2.0-based normalized message content (i.e.,
it is represented as a javax.xml.Source).
5.5.1.1.5 Message Properties
Message properties are metadata associated with the message content. The following properties are defined by
this specification, and MAY be used components:
• Security subject. This property indicates the identity of the JAAS subject which either signed a message,
or is to be used to sign a subject, as determined by processing context. getSecuritySubject() and
setSecuritySubject() are used to read and write this normalized message property.
• Name/value pair properties. This is an extensible set of properties, where components MAY set
properties for the use of other components, or for themselves. getProperty() and setProperty()
are used to read from and write to the property set; getPropertyNames() MAY be used to discover the
names of all of the properties defined.
5.5.1.1.6 Message Attachments
Attachments to a message are represented as a named set of entities, which are handled by Java Activation
Framework handlers. The following operations MAY be performed by components:
• Add an attachment to the normalized message, by unique name.
• Remove an attachment from the normalized message, by unique name.
• List the names of all attachments for the normalized message.
• Get an attachment, by unique name, from the normalized message.
Attachment content MUST be represented as javax.activation.DataHandler objects.

5.5.2 Service API

This API allows JBI components to interact with the NMR.
Figure 20 NMR API Classes

5.5.2.1 DeliveryChannel
The DeliveryChannel interface serves as the primary means for a JBI component to interact with the
NMR. It allows the component to
• receive and send messages
• create message exchange factories.
5.5.2.1.1 Message Exchange Factory API
All message exchange instances MUST be created using instances of the message exchange factory. Such
factories MUST be created in one of three ways, using the component’s DeliveryChannel:
• createMessageExchangeFactory(ServiceEndpoint). This creates a factory that sets the
endpoint property of all exchange instances created to the given endpoint. This is useful when dealing with
explicitly selected endpoints, or dynamically resolved endpoints.
• createMessageExchangeFactory(QName interfaceName). This creates a factory that sets
the interfaceName property of all exchange instances created to the given interface name.
• createMessageExchangeFactory(). This creates a factory that leaves all properties message
exchanges set to their default (null or empty) values.
• createExchangeFactoryForService(QName serviceName). This creates a factory that sets
the service property of all exchange instances created by the factory to the given service name.
5.5.2.1.2 Creating Message Exchanges
The MessageExchangeFactory provides three distinct ways to create new message exchange instances.
These support three different needs:
• createExchange(serviceName, operationName). Creation from service name and operation
name. This permits the component to quickly put together an ME instance, without the need of inspecting
MEPs in service metadata.
• createExchange(URI). Creation from MEP URI. This permits extensions to the supported MEPs.
• createInOnlyExchange(), etc. Creation using MEP-specific convenience methods. This is
convenient for creating standard MEs in situations where the MEP required is known at coding-time.
5.5.2.1.3 Sending Message Exchanges
The DeliveryChannel offers two basic means of sending message exchanges:
• send(exchange). Asynchronous message transmission: this method doesn't block. The exchange MAY
be delivered concurrent to the thread of execution that called send().
• sendSync(exchange). Synchronous message transmission: this method MUST block the current
thread of execution until the exchange is returned.
The latter method has a variant that adds a time-out parameter. This allows JBI components to use simple
synchronous message exchanges without needing to manage “stuck” threads if an exchange is not returned as
expected. To support this time-out feature, the sendSync() method returns a boolean value to indicate
successful return of the exchange instance. The first overload, sendSync(exchange), always returns
true. If the second overload, sendSync(exchange, long), returns false, the exchange is placed in
the ExchangeStatus.ERROR state. If a provider component attempts to send such an message exchange
(i.e, one that has failed because of a sendSync() time-out), the implementation MUST fail the send() call
with an appropriate MessagingException.
When a MessageExchange instance is sent using one of the sendSync methods, the JBI implementation
MUST set the following property on the message exchange instance:
javax.jbi.messaging.sendSync

This property MAY be used by servicers of such requests, as a hint that such exchanges should receive different
treatment.
Note that in the case of asynchronous exchanges, there is no guarantee that the message exchange received (by
the receiver's call to accept(), discussed in the next section) will be the same object that was initially sent.
Rather, the only guarantee is that the message exchange ID MUST be the same.
5.5.2.1.4 Receiving Message Exchanges
The DeliveryChannel offers two ways of receiving message exchanges:
• accept(). This method MUST block until a MessageExchange instance is received from the NMR.
• accept(timeoutMS). This method works similarly to accept(), except that it is blocked for the
given time-out interval, the method MUST return null, indicating that nothing was received.
Message reception always follows the “pull” model: the JBI component MUST pull the message exchange
instance from the DeliveryChannel, using its own thread of execution. Components MAY use more than
one such thread, allowing concurrent message reception by the component. The JBI implementation MAY
satisfy multiple accept() requests from a single component in arbitrary order.
5.5.2.1.5 Closing Down a DeliveryChannel
The component MAY deactivate all endpoints for the services it provides in a single DeliveryChannel call:
• close(). This method MUST cause all activate endpoints activated with the component (that is, all
services provided by the component) to be shut down, in the same fashion as if
deactivateEndpoint() was called for each active endpoint.
Once a DeliveryChannel is so closed, it cannot be re-opened. Instead, a new instance of
DeliveryChannel is needed to allow a component to resume interacting with the NMR.
When a DeliveryChannel is closed, all MessageExchangeFactory instances created by that channel
MUST no longer function normally; all attempts to create a message exchange instance with such a factory
MUST result in a MessagingException being thrown by the factory method invoked, indicating that the
associated delivery channel is closed.
5.5.2.2 Service Description SPI
With the Component interface, the component MUST supply service metadata concerning services it provides
in its implementation of the getServiceDescription(ServiceEndpoint) method. This method
MUST return a DOM Document, which provides a WSDL description of the service provided by the given
endpoint.1 This method MUST return null if the endpoint is not active, or if the endpoint is not provided by
the component.
The document provided MUST be either a WSDL 2.0-compliant document, or a WSDL 1.1-compliant
document, with the following additional properties:
• The document must not use the <wsdl:import> or <wsdl:include> elements (the document MUST
be stand-alone).
• Service Engine-provided endpoints MUST use the binding type defined in the section titled “JBI Service
Engine WSDL Binding” on page 57.
The document MUST provide the complete definition for the named service, and the named endpoint, including
the service's interface and operations (including, of course, the message exchange patterns used).
1.Note that this document must provide XML namespace information. Some XML parsers do not default to
"namespace aware" parsing, and must be explicitly configured to enable this feature.

5.5.2.3 Message Exchange Pattern APIs

The message exchange pattern APIs for all built-in MEPs, are depicted in the following figure:
Figure 21 Message Exchange Pattern API Class Diagram
All message exchange instances MUST be created by calls to suitable factory methods provided by instances of
MessageExchangeFactory.
MessageExchange instances are owned by either the initiator, servicer, or NMR. Creating or accepting a
message exchange instance confers ownership on the creating (or accepting) component. Upon calling send()
for a particular ME instance, the component surrenders ownership of the ME instance immediately.
sendSync() causes ownership to be surrendered during the course of the call; when the call ends (returning
true) the component resumes ownership of the ME instance.

Ownership of an ME instance gives the owner the right to read from and write to the instance. When a
component (or the NMR) doesn't have ownership of an ME instance, it MUST NOT read from or write to the
instance, except for reading the message exchange status, which can be queried regardless of ownership. If a
component that is not the current owner of the instance does attempt to call any method (other than
getStatus()) on the instance an appropriate java.lang.IllegalStateException MUST be
thrown.
5.5.2.3.1 MessageExchange
The super-interface, MessageExchange, provides common methods for all APIs that implement a specific
message exchange pattern. MessageExchange instances provide the context for a sequence of normalized
message interchanges as well as status interchange. The instance can be thought of as a stateful container for
normalized messages.
Each exchange instance has the following features which are accessed by using the MessageExchange API:
• Status. ExchangeStatus provides a type-safe enumeration of the possible values of an ME's status
during its life cycle. A new ME instance is ACTIVE, and remains so until the end of its life cycle, when it
transitions to either a DONE or ERROR state. The status can be queried and set using getStatus() and
setStatus(), respectively.
• Source of an ERROR status. This feature allows the instance to retain the root cause (Java exception) of a
processing failure. See getError() and setError().
• Exchange ID. Each instance of a MessageExchange MUST have a unique identifier string, assigned by
the JBI implementation. This identifier can be used by JBI components to associate asynchronous
responses with originating requests.
• Exchange Pattern. Each instance of a MessageExchange has a pattern identifier. The standard
Message Exchange Patterns are identified by their WSDL 2.0-assigned URIs.
• Exchange Role. When a component creates or accepts a message exchange instance, it must discover its
role in the on-going exchange. In simple exchange patterns this can easily determined, using the status,
message, and fault features of the exchange. However, it is easier, and in the case of complex exchange
patterns it is necessary, for the component use the getRole() method to determine its role in the
continuing exchange.
• Service name. The qualified-name of the service being invoked by this exchange.
• Operation name. The qualified-name of the operation being invoked by this exchange.
• Service endpoint name. The optional, fully-qualified name of the endpoint of the service provider (service
name plus endpoint name).
• Normalized messages. The instance serves as a factory for NormalizedMessages associated with the
exchange instance. Methods are provided to create, set, and query such messages. See
createMessage(), setMessage(), and getMessage().
• Fault messages. The instance serves as a factory for Fault messages associated with the exchange
instance. Methods are provided to create, set, and query such messages. See createFault(),
setFault(), and getFault().
• Transaction Context. If the transaction context is non-null, the message exchange is transacted. See
getProperty() and setProperty(); transactions are named by the constant
MessageExchange.JTA_TRANSACTION_PROPERTY_NAME.
• Properties. Non-JBI message exchange features can be stored as properties: name-value pairs, where the
value is (to JBI) an opaque java.lang.Object.

The MessageExchange API provides sufficient functions to support all standard MEPs. However, “in” and
“out” messages are not distinguished at the API level, making understanding of ongoing exchanges at a Java
code level difficult. To address this issue, a set of MEP-specific APIs are provided, and are detailed in the four
sections below.
5.5.2.3.2 InOnly Message Exchange
This sub-interface provides an API for the “http://www.w3.org/2004/08/wsdl/in-only” MEP.
This provides the following MEP-specific methods:
• setInMessage(msg). This can be called only once; subsequent calls MUST cause the implementation
to throw an appropriate MessagingException.
• getInMessage(). This can be called multiple times; if the setInMessage() method (or
setMessage(msg, "in")) has not been called, it MUST return null.
5.5.2.3.3 InOptionalOut Message Exchange
This sub-interface provides an API for the “http://www.w3.org/2004/08/wsdl/in-opt-out”
MEP. This provides the following MEP-specific methods:
• setInMessage(msg). This can be called only once, by the service consumer; subsequent calls to this
method MUST cause the implementation to throw an appropriate MessagingException.
• setOutMessage(msg). This can be called only once, by the service provider; subsequent calls to this
method MUST cause the implementation to throw an appropriate MessagingException. Setting the
“out” message is optional in this pattern.
• getOutMessage(). This can be called multiple times; if the setOutMessage() method (or
setMessage(msg, "out")) has not been called, it MUST return null.
5.5.2.3.4 InOut Message Exchange
This sub-interface provides an API for the “http://www.w3.org/2004/08/wsdl/in-out” MEP. This
provides the following MEP-specific methods:
• setOutMessage(msg). This can be called only once, by the service provider; subsequent calls to this
• getOutMessage(). This can be called multiple times; if the setOutMessage() method (or
setMessage(msg, "out")) has not been called, it MUST return null.
5.5.2.3.5 RobustInOnly Message Exchange
This sub-interface provides an API for the “http://www.w3.org/2004/08/wsdl/robust-in-
only” MEP. This provides the following MEP-specific methods:

5.5.2.3.6 WSDL 1.1 Message Exchange Properties

WSDL 1.1 allows overloading of operation names, creating situations where the precise operation desired in a
request-response message exchange (in-out message exchange pattern) cannot be determined simply by
examining the type of a request (in) message. In such cases service consumers should indicate which operation
is desired, by using one or more the following message exchange properties:
Property Name Property Value Type Description

javax.jbi.messaging.wsdl-11.output-type javax.xml.namespace.QName Output message type expected
from operation
javax.jbi.messaging.wsdl-11.output-name java.lang.String Output message name expected
from operation
javax.jbi.messaging.wsdl-11.fault-types javax.xml.namespace.QName[] Fault types allowed by operation
javax.jbi.messaging.wsdl-11.fault-names java.lang.String[] Fault names, in same order as the
fault types
Table 5 WSDL 1.1 Message Exchange Properties
A consumer SHOULD provide all available information, in the form of the above properties, to resolve the
ambiguity. If the consumer is unable to resolve the ambiguity by itself (and supply one or more of the above
properties), the consumer must send the message exchange, and allow the service provider the chance to resolve
the ambiguity.
For example, a SOAP binding component, serving as a consumer, may receive a request from an external
consumer for a service operation named “foo”. The WSDL 1.1 definition for foo includes the following:
<definitions xmlns ="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns ="http://www.example.com/xmlsvr"
targetNamespace ="http://www.example.com/xslsvr">
<types>...</types>
<message name="DoFooInput">...</message>
<message name="DoFooOutput1">...</message>
<message name="DoFooOutput2">...</message>
<portType name="FooPortType">
<operation name="Foo">
<input name="foo-in" message="tns:DoFooInput"/>
<output name="foo-out1" message="tns:DoFooOutput1"/>
</operation>
<operation name="Foo">
<input name="foo-in" message="tns:DoFooInput"/>
<output name="foo-out2" message="tns:DoFooOutput2"/>
</operation>
</portType>
</definitions>
There is an ambiguity for operation “Foo”. If the SOAP binding wishes to consume an internal service with the
above definition, it must use one of the following strategies to resolve it.
• Set the "javax.jbi.messaging.wsdl-11.output-type" property of the InOut message exchange to
either tns:DoFooOutput1 or tns:DoFooOutput2, to select the first or second version of Foo, respectively.
• Set the "javax.jbi.messaging.wsdl-11.output-name" property of the InOut message
exchange to either “foo-out1” or “foo-out2”, to select the first or second version of Foo, respectively.
• Set no additional properties of the InOut message exchange. Instead, the consumer relies on the provider
to choose which version of operation “Foo” to use.
The binding chooses its strategy based on implementation-specific information (such as SOAP action headers,
or additional configuration information).

5.5.3 Querying Activated Endpoints

Service consumers MAY query active endpoints, using the ComponentContext. (For details on the use of
this interface, please see the “Framework” chapter.) Queries may be made in several ways, but most return an
array of ServiceEndpoint objects. This array may contain zero or more endpoints; the consumer must be
prepared to deal with situations ranging from an unavailable service (zero endpoints) to having multiple
endpoints for accessing the same type of service. The query methods are:
• getEndpoint(). This method MUST return a specific active endpoint, matching a provided service
name and endpoint name, or null if there is no match.
• getEndpoints(QName interfaceName). This method MUST return all active endpoints that
implement the given interface/portType name. Supplying a null interfaceName parameter MUST
cause the method to return all active endpoints.
• getEndpointsForService(QName serviceName). This method MUST return all active
endpoints that belong to the given service name.
5.5.4 Endpoint Reference API

Endpoints (both internal and external) are defined in section 5.1.7, and the use of endpoint references (EPRs) in
section 5.4.4. This section defines the APIs needed to deal with EPRs in JBI.
EPRs are created by, and resolved by, components. The JBI implementation serves to facilitate interaction
between the components that can resolve (or create) EPRs, and those that need to use them.
For a component to resolve an EPR that it has received, it MUST call
ComponentContext.resolveEndpointReference().
For a component to resolve an EPR that it understands (typically a binding component), it MUST, in its
implementation of Component.resolveEndpointReference(), provide this ability.
Binding components that expose external endpoints that can be referred to by EPR MUST register such
endpoints using the ComponentContext.registerExternalEndpoint() method, indicating that
the external endpoint is active. deregisterExternalEndpoint() MUST be used to indicate that the
external endpoint is no longer active, and should not be included in the results from calls to
ComponentContext.getExternalEndpoints().
Components that want to generate EPRs MUST first select which external endpoint is to be referred to.
ComponentContext provides two methods for querying the external endpoints available in the JBI
environment:
• By interface name. getExternalEndpoints() MUST return an array of all registered external
endpoints that implement the given interface.
• By service name. getExternalEndpointsForService() MUST return an array of all registered
external endpoints that are included in the named service.
For example, let us suppose we have a service engine SE1, which provides a service through an endpoint EP1.
One consumer of this service is binding component BC2, which exposes an external endpoint EP2 to external
service consumers of EP1 (BC2 acts as a proxy for external consumers).
In one use case SE1 wishes to send a request message to an external service provider, and, in that message,
provide a “call back” address referring to EP2 (i.e., an EPR for EP2). The objective is to have the external
provider, acting as a consumer, use the EPR to send requests to EP2.
In this scenario, BC2 registers the external endpoint with JBI when it is created (at deployment time). SE1 can
find the external endpoint (using the above query methods), and use that endpoint to create an EPR for inclusion
in the request message to be sent to the external provider. (The task of creating the EPR is given to BC2). The
external providers uses the EPR to send the needed message to EP2, the external endpoint.

5.5.4.1 Internal EPR Vocabulary

EPRs for internal endpoints offered by service engines, as defined in section 5.1.7 above, MAY be referenced
by components using the XML schema defined in this section. This type of EPR is only useful within the JBI
environment, and is provided to allow consistent use of EPRs for both internally- and externally-provided
services. Endpoint references generated for endpoints provided by service engines MUST conform to the
default namespace jbi = "http://java.sun.com/jbi/end-point-reference"

start =
element end-point-reference {
attribute service-name { xsd:QName },
attribute end-point-name { text },
empty
}
Listing 4 Schema for JBI Internal Endpoint References (Relax NG)
schema shown in the above listing.
5.5.5 Usage Examples

This section provides detailed examples on common BC, SE, and NMR interactions. The areas of run-time
activation and message exchange are covered in detail.
5.5.5.1 Service Consumer
This example takes place within a single JBI environment. A service engine, ConsumerEngine, is the consumer
of an external web service (i.e. outbound service invocation).
Notes:
• Service name: {http://abc.com/services}: service1
• Endpoint name: soap1
• Direction: Outbound
• Operation(s): updateStatus (one way)
• For simplicity, BC and SE are single-threaded and only participate in one exchange during the course of
this example.
• Assume the following constants are declared:
• QName SERVICE1 = new QName("http://abc.com/services", "service1");
• QName OP_UPDATE_STATUS = new QName("http://abc.com/services", "updateStatus");
• String ENDPOINT1 = “soap1”;

5.5.5.1.1 SE Initialization
Prior to the first "start" of a component, its "init" method is called to perform pre-start initialization. In this
class ConsumerEngine implements Component, ComponentLifeCycle,

{
DeliveryChannel channel;
MessageExchangeFactory factory;
public void init(ComponentContext context)
throws JBIException
{
// Obtain reference to delivery channel
channel = context.getDeliveryChannel();
// Create our ME factory; we use a single factory for all exchanges
factory = channel.createMessageExchangeFactory();
}
// ...
}
Listing 5 Service Engine Initialization
example service engine, the delivery channel and message exchange factory are made ready.
5.5.5.1.2 BC Initialization
Prior to the first "start" of a component, its "init" method is called to perform pre-start initialization. In the same
class ConsumerEngine implements Component, ComponentLifeCycle,

{
throws JBIException
{
// Create our ME factory; we use a single factory for all exchanges
}
// ...
}
Listing 6 Service Engine Initialization

class SoapBinding implements Component, ComponentLifeCycle {

ServiceEndpoint serviceEndpoint;
throws JBIException {
// Activate endpoint names
serviceEndpoint = context.activateEndpoint(SERVICE1, ENDPOINT1);
}
public Document getServiceDescription(ServiceEndpoint ref) {
Document result = null;
// return WSDL describing services offered by me through the given
// service reference.
if (ref.getServiceName.equals(SERVICE1) &&
ref.getEndpointName.equals(ENDPOINT1) ) {
//... create or find the WSDL
}
return result;
}
// ...
}
Listing 7 Binding Component Initialization
fashion as the service engine above, this component prepares by creating a delivery channel and a message
exchange factory.
5.5.5.1.3 Message Exchange
Engine View
void someEngineMethod()
{
InOnly inOnly;
Message message;
// As initator, we get to create the message exchange
inOnly = factory.createInOnlyExchange();
// Create new message for this exhange.
message = inOnly.createMessage();
// Populate message with data (omitted)
// Set message as in reference in exchange
inOnly.setInMessage(message);
// Set operation and service details
// (We could avoid this by using channel.createExchange(SERVICE1,
// OP_UPDATE_STATUS); above)
inOnly.setOperation(OP_UPDATE_STATUS);
inOnly.setService(SERVICE1);
// We will allow the NMR to select the endpoint automatically.
// Alternatively, we could query the available endpoints implementing SERVICE1,
// choose from that list, and use inOnly.setEndpoint() to route the ME ourselves.
// Initiate the message exchange
channel.send(inOnly);
}
Listing 8 Message Exchange: Service Engine View

Binding View
void someBindingMethod()
{
MessageExchange exchange = channel.accept();
if (exchange instanceof InOnly)
process((InOnly) exchange);
else // ...
}
void process(InOnly inOnly)
{
NormalizedMessage inMsg;
// fetch "in" message from exchange
inMsg = inOnly.getInMessage();
// process data
try
{
// commit message to wire (omitted)
// set status appropriately
inOnly.setStatus(ExchangeStatus.DONE);
}
catch (Exception ex)
{
// Implicitly sets inOnly status to ExchangeStatus.ERROR
inOnly.setError(ex);
}
channel.send(inOnly);
}
Listing 9 Message Exchange: Binding View
5.5.5.2 Service Provider (Servicer)

This example takes place within a single JBI environment. A service engine, ProviderEngine, provides a service
to external consumers (i.e. inbound service invocation) through a SOAP binding component.
Notes:
• Service name: {http://xyz.com/services}: service2
• Endpoint name: engine2
• Direction: Inbound
• Operation(s): getStockQuote (request -response)
• For simplicity, BC and SE are single-threaded and only participate in one exchange during the course of
this example.
• Assume the following constants are declared:
• QName SERVICE2 = new QName("http://xyz.com/services", "service2");
• String ENDPOINT2 = "engine2";

5.5.5.2.1 BC Initialization
class SoapBinding implements Component, ComponentLifeCycle {

throws JBIException {
// Create single ME factory; we will use it for creating all exchanges needed
// Create listener for inbound SOAP messages
// (omitted)
}
}
Listing 10 Example SOAP Binding Component Initialization
5.5.5.2.2 SE Initialization
class ProviderEngine implements Component, ComponentLifeCycle {

ServiceEndpoint serviceEndpoint;
throws JBIException
{
// Activate service endpoint (SEVICE2,ENDPOINT2)
serviceEndpoint = context.activateEndpoint(SERVICE2, ENDPOINT2);
}
public Document getServiceDescription(ServiceEndpoint ref) {
Document result = null;
// return WSDL describing services offered by me through the given
// service reference.
if (ref.getServiceName.equals(SERVICE2) &&
ref.getEndpoint Name.equals(ENDPOINT2) ) {
//... create or find the WSDL
}
return result;
}
// ...
}
Listing 11 Example Service Engine Initialization
5.5.5.2.3 Message Delivery

Binding View
void someBindingMethod() {
InOut inOut;
// Receive message over native protocol (omitted)
// Create InOut exchange
inOut = factory.createInOutExchange();
// Create new message
inMsg = inOut.createMessage();
// Normalize native protocol data (omitted)
// Set message as in reference in exchange
inOut.setInMessage(inMsg);
// Set operation and service details
inOut.setOperation(new QName(SERVICE2.getNamespaceURI(), "getStockQuote"));
inOut.setService(SERVICE2);
// Initiate the message exchange and wait for response
channel.sendSync(inOut);
process((InOut) inOut);
}
void process(InOut inOut) {
NormalizedMessage outMsg = inOut.getOutMessage();
if (inOut.getStatus() != ExchangeStatus.ACTIVE) {
// error occurred. Return error response in native wire protocol (omitted)
} else {
// commit response message to native wire protocol (omitted)
// Tell provider that the exchange is now complete.
inOut.setStatus(ExchangeStatus.DONE);
channel.send(inOut);
}
}
Listing 12 Example Binding Using Synchronous Message Exchange for Service Invocation

Engine View
void someEngineMethod() {
MessageExchange exchange = channel.accept();
if (exchange instanaceof InOut)
process((InOut) exchange);
else // ...
}
void process(InOut inOut) {
NormalizedMessage outMsg;
// fetch in message
inMsg = inOut.getInMessage();
// process data
try {
// perform appropriate processing to inMsg (omitted)
// create response message
outMsg = inOut.createMessage();
// populate message content (omitted);
// attach message to exchange
inOut.setOutMessage(outMsg);
}
catch (Exception ex) {
// Implicitly sets inOut status to ExchangeStatus.ERROR
inOut.setError(ex);
}
channel.send(inOut);
}
Listing 13 Example Engine Service Provider
5.5.5.3 Resolution of Dynamic Endpoint Reference

An example of resolution of an EPR by a service consumer is shown in the following listing.
MessageExchange createExchangeForEPR(DocumentFragment epr, QName operationName)

throws MessagingException, Exception
{
MessageExchange result;
ServiceEndpoint endpoint = context_.resolveEndpointReference(epr);
if (endpoint != null) {
result = channel_.createExchangeFactory(endpoint).
createExchange(endpoint.getServiceName(), operationName);
}
else {
throw new Exception("Cannot resolve EPR");
}
return result;
}
Listing 14 Example Resolution of an EPR by a Service Consumer

5.5.5.4 Creation of a Dynamic Endpoint Reference

An example of creation of an EPR by a service provider is shown in the following listing.
private DocumentFragment getEpr(QName interfaceName, QName operationName) {

DocumentFragment result = null;
ServiceEndpoint[] endpoints = context_.getExternalEndpoints(interfaceName);
if (endpoints.length > 0) {
ServiceEndpoint endpoint = endpoints[0]; // simple choice
result = endpoint.getAsReference(operationName);
}
return result;
}
Listing 15 Example Creation of an EPR by a Service Provider
5.5.6 Service Provider Metadata

Each service provider MUST provide an implementation of the Component
getServiceDescription() method. This method MUST be called by the NMR when it wishes to
retrieve metadata about services provided by the component. Such services MUST have been previously
activated (by name) with the NMR.
JBI supplements standard WSDL 1.1 and 2.0 by adding a JBI-specified binding type, which MUST be used by
service engines when declaring the endpoint for a service provided by that engine. This binding type is defined
in the next subsection.
5.5.6.1 JBI Service Engine WSDL Binding
A JBI 1.0 service engine binding is identified by assigning the value
“http://java.sun.com/xml/ns/jbi/binding/service+engine”
to the type property of a WSDL binding component, as defined in [WSDL 1.1] and [WSDL 2.0].
This binding type serves to identify service engines (i.e., local service providers within the JBI environment). It
does not define a mapping of WSDL operations or messages; all abstract WSDL definitions are used without
modification.


CHAPTER 6
Management
As mentioned in the architecture overview section, the JBI environment is administered using JMX. This
includes the JBI components (the plug-in bindings and engines), which must provide specified management
interfaces. In addition, the JBI implementation must provide specified JMX Management Beans (MBeans) to
facilitate management of the JBI environment-provided infrastructure as well as the JBI components.In
addition, JBI implementations must provide a set of Apache Ant tasks specified in this chapter.
6.1 Overview
The major administrative tasks that are supported by this specification are:
• Installation of JBI components and shared libraries.
• Deployment of artifacts (opaque to JBI) to installed components.
• Starting and stopping components (binding and engines), as well as JBI implementation components (if
applicable).
• Starting and stopping groups of related services (composite assemblies).
All of these use cases assume the presence of an administrative tool, which serves to initiate activities using
JMX. JBI implementations provide particular MBeans that expose management functions to the administrative
tool. The MBeans are:
• InstallationServiceMBean. The administrative tool uses this management bean to install and uninstall
components and shared libraries.
• InstallerMBean. JBI implementations provide one of these per component installation started with the
InstallationServiceMBean. This is used to manage the installation process, including component-
supplied installation configuration via the component’s own MBean.
• DeploymentServiceMBean. The administrative tool uses this bean to deploy and undeploy artifacts to
components, as well as control the running state of individual deployments.
• LifeCycleMBean. The administrative tool uses this bean type to stop and start pieces of the JBI
implementation (use of this MBean is implementation dependent).
• ComponentLifeCycleMBean. The administrative tool uses this bean type to stop and start components.
The component may supply additional life cycle controls, using a component-supplied extension MBean.

Management
In addition, components MAY expose their own MBeans, to provide component-specific management
functions beyond the life cycle and installation extensions mentioned above. For example, a component can
expose an MBean to manage internal logging levels.
Installation and deployment involve having the administrative tool deliver standardized packages to the
appropriate MBeans, listed above. JBI specifies how such packages are structured, including standard XML
descriptors of the packages.
6.2 Key Concepts

JBI components (engines and bindings) are installed using standard management mechanisms, defined in this
chapter. Standard packaging for such components is also defined here. The objective is to ensure the portability
of components, including installation artifacts. This allows component vendors to produce a single package for
distribution, rather than multiple variants based on which JBI implementation is targeted. This also benefits
users by simplifying component acquisition and management logistics.
6.2.2 Shared-library Installation

Java libraries can be shared between multiple components. These are installed using standard management
mechanisms.
6.2.3 Deployment
Many components function as containers, providing (or consuming) services based on artifacts contained by the
component. For example, an XSLT engine contains multiple style sheets, each providing a specific
transformation service.
The act of introducing new artifacts to a container component is called deployment, to distinguish it from
component or shared-library installation.
6.2.3.1 Unit Deployment
A single deployment package, destined for a single component, is termed a Service Unit, or SU. The contents
of a SU are opaque to JBI (other than a single descriptor file), but are transparent to the component to which it is
being deployed, as well as the design-time tooling that produced the artifacts contained by the SU. The service
unit must contain a single JBI-defined descriptor file that defines the static services produced and consumed by
the service unit. This is useful for tooling that is used to create composite deployments, as defined below.
6.2.3.2 Composite Deployment
Often multiple deployments are required to create a new service or consumer application within a JBI
environment. To support this directly, JBI provides a composite deployment capability, where deployments
meant for different components can be grouped into a Service Assembly, or SA. Such an assembly includes a
composite service deployment descriptor, detailing to which component each Service Unit contained in the SA
is to be deployed. Note that this service assembly concept is sometimes termed “composite service description”,
or CSD.
A service assembly represents a composite service. Because of this interrelationship, JBI provides management
functions to control the life cycles of the individual units of a service assembly collectively, rather than
individually.

Management
6.2.3.3 Composite Service Metadata

The deployment descriptor also includes information about service connections made between service units and
service providers, permitting recomposition of assemblies. These data fall into two categories:
• Description of static services provided and consumed as a result of deployment of a service unit.
• Description of static service interconnections between the services units of the service assembly, as well as
dependencies on services offered outside of the service assembly (i.e, services provided elsewhere in the
JBI environment.
The former category allows tools to inspect the static service dependencies and offerings of a service unit,
without needing to analyze the contents of the service unit. These data may also be used by components
themselves, to provide configuration data for the deployment of the service unit itself.
The latter category allows the composer of the service assembly to change the connections between static
service consumers and providers, by declaring new connections between consumers and providers. These
connections serve to rename a provider endpoint, such that when a consumer asks for a particular service
endpoint a different one is actually used.
For example, suppose we have the following metadata in a service assembly:
• SU1 consumes an endpoint named EP1,
• EP1 is connected to EP2.
After the service assembly is successfully deployed, when the component to which SU1 was deployed sends a
message exchange to EP1, it will be routed to EP2 instead.1
1.This is a simplified explanation. See section 6.6.3 and the “Normalized Message Router” chapter, section
5.4.3.3, for a full explanation of how connections must be handled by the implementation.

Management
These composite service metadata can be viewed schematically, as shown below. This example is based on the
Figure 22 Composite Service for Example One-way Message Adapter (from Architecture chapter)
one-way message adapter example application, given in the “Architecture of the JBI Environment” chapter.
BC1 serves as a proxy service consumer for the external client, BC2 serves as a proxy service provider. SE2 is
the transformation service provider, while SE1 orchestrates the overall service, serving both as provider and
consumer in the course of the orchestration. The service assembly connections serve to connect SE1 to the
services provided by SE2 and BC2, and BC1 to the one-way adapter service provided by SE1.
Use of composite service metadata, as described here, is only one of several methods JBI provides for
connecting service consumers to providers. See the “Normalized Message Router” chapter for details on
implicit endpoint selection by service type, dynamic endpoint selection by the consumer, and message exchange
address types.

Management
6.2.4 Deployment Life Cycle

Each deployment to a component (each service unit) has a simple life cycle model, provided by JBI-specified
interfaces. This is illustrated in the figure below. This is similar to the component life cycle.
deploy() init() start()

empty shutdown stopped started
undeploy() shutDown() stop()
Figure 23 Deployment Life Cycle State Diagram
6.2.5 Component Life Cycle

Each component has a simple life cycle model, managed by JBI-specified management interfaces. This model
can be extended by the component to add additional states.The basic life cycle model is shown in the state
diagram below.
onInstall() init() start()

empty shutdown stopped started
onUninstall() shutDown() stop()
Figure 24 Base Component Life Cycle State Diagram
The extended life cycle of a component is the base life cycle, as depicted above, plus states introduced by the
installation and uninstallation of the component. In addition, the base component life cycle MAY be extended
by a component by use of an extension MBean. For example, a component may add a “paused” sub-state to the
“Started” state, which is entered by use of the controls offered by an extension MBean.
6.2.6 Class Loading

A JBI implementation MUST provide class loaders to create the component’s Bootstrap and Component
implementations (these are detailed in the “Framework” chapter). Such class loaders provide access to classes
available in a declared class path, as described in the Java Language Specification [JLS]
(java.lang.ClassLoader). There are two types of class loaders used during the extended life cycle of
the component:
• Bootstrap. During the installation and uninstallation phases of a component’s extended life cycle, the class
loader provided for component-supplied installation methods MUST provide access to the bootstrap class
path. It MUST be used by the JBI implementation to create an instance of the component’s Bootstrap
implementation.
• Execution. After installation, the component enters the execution phase of its extended life cycle. The class
loader supplied by the JBI implementation for the execution phase MUST supply access to classes in the
component’s declared class path, plus any shared libraries used by the component. This class loader MUST
be used by the JBI implementation to create instances of the component’s Component implementation.

Management
The component class loader is detailed in chapter 7, “Component Framework.”
6.2.7 Use of Java Management Extensions (JMX)

Java Management Extensions (JMX) provides the basis of the interaction between an administrative device
(command-line script engine, Ant script, browser UI, or graphical UI) and the JBI environment, including JBI
components. JBI implementations MUST support JMX 1.2.1 or newer.
To support JBI-specified administrative functions, JBI components MUST implement specified JBI (Java
language) interfaces, while the JBI implementation itself supplies specified JMX MBeans that make use of the
component-implemented interfaces. For example, an administrative tool uses an implementation-supplied
MBean to perform deployment, which in turn will use a component-supplied ServiceUnitManager
interface to deploy service units to that component.
Components MAY supply their own MBeans to perform additional management tasks that fall outside the
bounds of this specification. The mechanisms for this are detailed in “Component Installation” on page 72, and
“Component Life Cycle” on page 63.
6.2.8 Use of the Apache Ant for Scripting

Apache Ant serves as the basis for a standard scripting language for JBI implementations. As mentioned in the
section above, the implementation of Ant tasks, as defined in this chapter, must utilize the JMX administrative
interfaces defined here.
6.3 Packaging
JBI defines standard packaging for both installation of components and deployment of artifacts to those
components that function as “containers”, as discussed above in section 6.2.3. For the installation case, a single
descriptor is used. In the deployment case two descriptors are used:
• Service assembly descriptor. This is used to describe the contents of a service assembly. Primarily it
described where the various service units that are included in the assembly are to deployed.
• Service unit descriptor. This is used to describe the services provided and consumed by a service unit.
Because of the similarity between all of these descriptor types, a single schema is employed for both.

Management
6.3.1 Installation and Deployment Descriptors

The schema used for creating both the installation descriptor and the two deployment descriptors is shown
below, in two listing using RelaxNG compact notation for clarity.
default namespace this = "http://java.sun.com/xml/ns/jbi"

start =
element jbi {
( component | shared-library | service-assembly | services)
}
component =
element component {
attribute type { "service-engine" | "binding-component" },
attribute component-class-loader-delegation { "parent-first" | "self-first" }?,
attribute bootstrap-class-loader-delegation { "parent-first" | "self-first" }?,
identification,
element component-class-name { attribute description { text }?, text },
element component-class path { class path },
element bootstrap-class-name { text },
element bootstrap-class path { class path },
shared-library-list*,
element* -this:* { text }*
}
shared-library =
element shared-library {
attribute class-loader-delegation { "parent-first" | "self-first" }?,
attribute version { text }?,
identification,
element shared-library-class path { class path }
}
shared-library-list =
element shared-library {
attribute version { text }?,
text
}
service-assembly =
element service-assembly {
identification,
service-unit*,
connections?,
}
service-unit =
element service-unit {
identification,
element target {
element artifacts-zip { text },
element component-name { xsd:NCName }
},
}
identification =
element identification {
element name { xsd:NCName },
element description { text },
}
class path =
(element path-element { text })+
Listing 16 jbi.xml Schema (Relax NG) Part 1

Management
services =
element services {
attribute binding-component { xsd:boolean },
provides*,
consumes*,
}
connections =
element connections {
element connection {
element consumer {
( attribute interface-name { xsd:QName } |
(attribute service-name { xsd:QName }, attribute endpoint-name { text })
)
},
element provider {
attribute service-name { xsd:QName }, attribute endpoint-name { text }
}
}*,
}
provides =
element provides {
attribute interface-name { xsd:QName },
attribute service-name {xsd:QName }, attribute endpoint-name { text },
}
consumes =
element consumes {
attribute interface-name { xsd:QName },
( attribute service-name {xsd:QName }, attribute endpoint-name { text },
attribute link-type { "standard" | "hard" | "soft" }? )?,
}
Listing 17 jbi.xml Schema (Relax NG) Continued
The following subsections detail the use of the productions contained in the “jbi” schema for jbi.xml files.
6.3.1.1 Use of jbi
The top-level production is “jbi”. This serves as the starting point for all deployment and installation descriptors
generated by this schema.
• Attribute version is a decimal value indicating the version of descriptor in use. For this version of JBI, this
value MUST be 1.0.
• The type element indicates what type of descriptor this is. It must be one of the following elements:
• component. This indicates that an installation package is described by the descriptor.
• service-assembly. This indicates that a deployment package is described by the descriptor.
• shared-library. This indicates that a shared-library installation package is described by the descriptor.
• services. This indicates that the descriptor is a service unit self-description.
The use of these different descriptor types is detailed below.
6.3.1.2 Use of identification
The identification production is used to provide identifying information for components, shared libraries,
service units, and service assemblies (which are collectively referred to as items here). The identification
production contains the following data:
• name. The name of the item. This is a human-friendly identifier for the item. Note that each item type
imposes other restrictions on name (e.g., uniqueness).
• description. A longer (one sentence) description of the item.

Management
• extension elements (optional). Additional, vendor-specific identification information. These are not used
by JBI, but it is anticipated that tools used to create and manipulate the package identified will require
additional identifying information.
6.3.1.3 Use of class path
The class path production is used to declare a Java class path for components and shared libraries. Each path
element given is a path that is rooted as follows:
• Component bootstrap-class path and component-class path: rooted in the component’s installation
package installation root. See chapter “Component Framework” for details.
• Shared library shared-library-class path: rooted in the shared-library’s installation package installation
root. See chapter “Component Framework” for details.
Each path element must use the forward slash (’/’) as the file separator character.
6.3.1.4 Use of shared-library
The shared-library production is used to describe a shared-library installation package. It has the following
elements:
• version. This is used to indicate the version of the shared library. See the component shared-library-list /
shared-library version attribute.
• identification. This is used to provide identifying information for the shared-library. The name provided
must be unique among all installed shared-libraries in the JBI environment.
• shared-library-class path. This declares the class path elements (rooted in the shared-library installation
package) that are given to the components that use the shared library.
In addition, shared-library has the following attribute:
• class-loader-delegation. If this optional attribute has a value of "self-first", the class loader for the
shared-library will invert its default delegation model ("parent-first"), instead loading classes from
the loader first. See the “Class Loading” section of the “Framework” chapter for details.
6.3.1.5 Use of service-assembly
The service-assembly production is used to describe a service assembly deployment package. This deployment
descriptor describes the contained service units, and to which components they are to be deployed.
• identification. The name given is a unique identifier (among all service assemblies deployed to the JBI
environment) for the composite deployment.
• service-units. These elements describe the individual deployments to be made to components. See below
for details.
• connections. This optional element contains declarations of service interconnection metadata, used to map
static service consumers to service providers.
6.3.1.6 Use of service-unit
The service-unit production is used to describe a service component within a service-assembly deployment
package.
• identification. This provides a unique name (unique among service-units deployed to the target
component) for the service-unit.
• target.
• artifacts-zip. The name of the artifact archive file within the deployment package that will be deployed
• component-name. The name of the component that will have artifacts-zip deployed to it.

Management
The deployment process is described in detail in “Deployment Service” on page 78.

6.3.1.7 Use of component
The component production is used to describe a component installation package.
• type specifies whether the component is a service engine or a binding component. This must be used by JBI
implementations to distinguish between the two component types (for management query purposes).
• component-class-loader-delegation. If this optional attribute has a value of "self-first", the class
loader for the component will invert its default delegation model ("parent-first"), instead loading
classes from the component class loader first.
• bootstrap-class-loader-delegation. If this optional attribute has a value of "self-first", the class
loader for the component bootstrap will invert its default delegation model ("parent-first"), instead
loading classes from the bootstrap class loader first.
• bootstrap-class path is the class path used during installation processing (bootstrapping) of the
component. See “Installation Service” on page 71 for details on component installation processing.
• bootstrap-class-name is the fully-qualified class name for the component’s Bootstrap implementation.
This is used during component installation, and is detailed in “Component Installation” on page 72.
• component-class path is the class path used after the component is installed. This class path, along with
shared-libraries, constitutes the full class path available to the component through its default class loader
context as provided by JBI. See chapter “Component Framework” for details.
• component-class-name is the fully-qualified class name for the component’s Component
implementation. This is used during component’s execution phase of its lifecycle.
• shared-library-list provides a list of shared libraries (by name and optional version) used by the
component. The implementation may use the version information to verify that the shared library version
declared by the component matches the version of the shared library installed in the JBI environment.
• Installation extension data. Optional component-specific installation data can be supplied at the end of the
component element. Such extension elements must not be in the jbi.xml name space. The component can
access these data using its
InstallationContext.getInstallationDescriptorExtension() method.
6.3.1.8 Use of connections
The connections element is used to declare interconnection metadata for the assembly, as a set of connection
elements. These data declare mappings from consumer-provided message exchange addresses to provider
service endpoints. The use of interconnection metadata is detailed in section 6.6.3.
6.3.1.9 Use of connection
The connection element declares a mapping from consumer-provided service address to a provider’s service
endpoint address. This mapping applies to consumption of services by all components.The consumer
subelement is used to declare the type of consumer address that is to be mapped (or connected). This declaration
can take two forms:
• service type. This specifies a service type, by supplying an interface-name attribute. All applicable
exchanges that are addressed to the given service type are to be sent to the given service provider endpoint
instead.
• service endpoint. This specifies a service endpoint, by supplying a service-name attribute and an endpoint-
name attribute. All applicable exchanges that are addressed to the given service endpoint are to be sent to
the given service provider endpoint instead.

Management
The provider subelement is used to declare the service provider endpoint to which the consumer is to be
connected. This element provides two attributes to declare the provider service endpoint: service-name and
endpoint-name.
6.3.1.10 Use of services
The services element is used to declare the static services provided and consumed by a service unit. The term
“static” in this context means those services that are provided or consumed due to the deployment of the service
unit, and that are known at design- and/or deployment-time.
• The binding-component attribute is supplied for the use of off-line tools, that may wish to distinguish
between service engines and binding components. It has no effect on the deployment process. An
implementation may provide a warning (as part of the deployment result/status) if the component’s type (as
declared in its installation descriptor) is not consistent with this attribute’s value.
6.3.1.11 Use of provides
The provides element is used to declare a service provided by a service unit. A provided service is declared with
the following attributes:
• interface-name. This qualified name indicates the type of service to be provided.
• service-name and endpoint-name. This pair of attributes declares the name of the endpoint that the
service unit will, after deployment, activate with JBI.
6.3.1.12 Use of consumes
The consumes element is used to declare a service consumed by a service unit. A consumed service must be
defined with the following required attribute:
• interface-name. This qualified name indicates the type of service to be consumed.
Optionally a fully qualified name of the endpoint the SU will use to consume the service can be specified. See
section 6.6.3 for a description of how this optional service endpoint name is used. If the service endpoint is
declared, an optional attribute can be supplied:
• link-type. This attribute is used to indicate the expected use of this consumer with connection links. The
possible values of this attribute are:
• standard. This is the default value. This indicates that the provided service endpoint must be routed
according to standard normalized message routing rules.
• hard. This indicates that the provided service endpoint name must match a service provider’s service
endpoint name; indirect connections are not allowed.
• soft. This indicates that the provided service endpoint must not match a service provider’s service
endpoint name; rather, it must match an indirect connection name.
See section 6.6.3 for details on how these values affect normalized message routing.
6.3.2 Installation Packaging

Installation packages contain everything that is needed to install a JBI component into a JBI system, or to install
a shared-library for use by such components. This includes an installation descriptor, which provides
information for the JBI installation service to process the contents of the installation package appropriately. The
actual installation process is described in “Installation Service” on page 71.
The installation package itself is a ZIP archive file, which has contents that are opaque to JBI except for one
installation descriptor that MUST be named and located as follows:
/META-INF/jbi.xml

Management
The contents of the installation descriptor file MUST conform to either the component installation descriptor
schema or the shared-library installation descriptor schema, as described above.
An example of an installation descriptor is shown below.
<?xml version="1.0" encoding="utf-8"?>

<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi"
xmlns:foo="http://www.foo.com/ns/bar">
<component type="service-engine">
<identification>
<name>example-engine-1</name>
<description>An example service engine</description>
<foo:TypeInfo part-number="012AB490-578F-114FAA">
BPEL:2.0:XQuery:1.0:XPath:2.0:XPath:1.0
</foo:TypeInfo>
</identification>
<component-class-name description="foo">com.foo.Engine1</component-class-name>
<component-class path>
<path-element>Engine1.jar</path-element>
</component-class path>
<bootstrap-class-name>com.foo.Engine1Bootstrap</bootstrap-class-name>
<bootstrap-class path>
<path-element>Engine1.jar</path-element>
</bootstrap-class path>
<shared-library>slib1</shared-library>
<foo:Configuration version="1.0">
<foo:ThreadPool size="10"/>
<foo:Queue1 size="50"/>
</foo:Configuration>
</component>
</jbi>
Listing 18 Example Component Installation Descriptor jbi.xml
The example includes two “extension” elements, providing component-specific information, using an XML
name space that is outside of the document element’s. JBI implementations and component implementations
MAY use these extension elements to provide extra, component-specific data for the use of the component,
component tooling, or both.
Components vendors SHOULD use the identification extension element to provide identity information about
the component beyond the required JBI name and description. Such information could allow component-
specific tools to recognize the installation package type, and perform additional operations on the package or
the descriptor. This information is available to the component at both bootstrap and execution time (the jbi.xml
file is available at META-INF/jbi.xml relative to the installation root directory).
Components SHOULD use the component extension element to provide configuration information that is
known before installation is performed. The relationship between such configuration data and configuration
MBean-determined configuration data is determined by the component implementation. This information is
made available to the component through the InstallationContext interface.
6.3.3 Service Assembly Packaging

Service assembly packages contain opaque (to JBI) deployment artifacts, and a deployment descriptor, which
provides information for the JBI deployment service to process the contents of the deployment package
appropriately. The deployment process is described in “Deployment Service” on page 78.
The deployment package itself consists of a deployment descriptor, and one or more service unit archives, all
contained within a ZIP archive file. The file/directory structure of this archive is as follows:
• /META-INF/jbi.xml. This contains the deployment descriptor, which MUST conform to the deployment
descriptor schema described above.
• /{artifacts-file-name.zip}. This is the name of one of the service unit archives, as given in one of the
deployment descriptor’s target elements.

Management
• /{artifacts-file-name-N.zip}. As many service unit archives as are needed provide all such archives
mentioned in the deployment descriptor jbi.xml.
An example deployment descriptor and deployment package directory are given below. The descriptor makes

<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi">
<service-assembly>
<identification>
<name>example-deployment-1</name>
<description>An example deployment of two service units</description>
</identification>
<service-unit>
<identification>
<name>SU-1</name><description>service unit 1</description>
</identification>
<target>
<artifacts-zip>su1-artifacts.zip</artifacts-zip>
<component-name>bpel-engine-1</component-name>
</target>
</service-unit>
<service-unit>
<identification>
<name>SU-2</name><description>service unit 2</description>
</identification>
<target>
<artifacts-zip>su2-artifacts.zip</artifacts-zip>
<component-name>xslt-engine-1</component-name>
</target>
</service-unit>
</service-assembly>
</jbi>
Listing 19 Example Service Assembly Deployment Descriptor jbi.xml
/META-INF/jbi.xml
/su1-artifacts.zip
/su2-artifacts.zip
Listing 20 Example Deployment Package Directory
reference to two separate files in the deployment package. Those two files, plus the descriptor itself, are
combined into a single ZIP archive, as shown in Listing 20.
6.3.4 Service Unit Packaging

Service unit archives MUST contain a single JBI-defined descriptor file:
• /META-INF/jbi.xml. This contains the service unit descriptor, which MUST conform to the services
schema described above.
The service unit descriptor provides information about the services statically provided and consumed as a result
of deploying the service unit to its target component.
6.4 Installation Service

The installation service allows the administrative tool to install and uninstall components and shared-libraries to
and from the JBI environment.

Management
Installation of components allows the component to supply an optional extension MBean to provide extended
configuration capabilities. Installation of shared-libraries does not allow for extended configuration, and thus
follows a simpler installation process. These two types of installation are detailed below.
Both types of installation begin with the JBI InstallationServiceMBean, a JMX management bean that
JBI implementations MUST provide. Once installed, individual shared libraries and components are referred to
by name. The term “name” in this context always refers to the unique library or component name, supplied in
the installation descriptor’s <identification><name> element value.
6.4.1 Shared Library Installation

Shared library installation packages can be installed and uninstalled, as follows, using the
InstallationServiceMBean:
• Install. The administrative tool installs a shared library by invoking the installSharedLibrary()
method on the installation service MBean, supply a URL indicating where the installation package may be
found. The installation package MUST have a shared library installation descriptor.
• Uninstall. The administrative tool uninstalls a shared library by invoking the
uninstallSharedLibrary() method on the installation service MBean, supplying a shared library
name to indicate which shared-library to remove. The name must match the installation descriptor-supplied
library name provided during shared library installation.

Component installation is somewhat more complex than shared-library installation. The administrative tool
must create or recall a separate InstallerMBean management bean, using the
InstallationServiceMBean. An InstallerMBean is used to manage the installation of an
individual component.
The installer MBean is managed from the InstallationServiceMBean as follows:
• Create installer. Invoke the loadNewInstaller() method, supplying an installation package URL.
This returns a JMX ObjectName for the newly created installer.
• Recall installer. Invoke the loadInstaller() method, supplying the component’s name. This MUST
return the same ObjectName MBean as returned when the component was installed.
• Remove installer. Invoke the unloadInstaller() method, supplying the component’s name.
Optionally, this method can be used to remove the component itself.
The InstallerMBean is used to manage the installation of the component itself:
• Install the component. Using the install() method, the administrative tool causes the component to
be installed as detailed in “Installation Process” on page 72. The method returns the JMX ObjectName of
the ComponentLifeCycleMBean for the newly installed component.
• Configure the installer. Prior to installing the component, the installer can optionally be configured, using
the installer configuration MBean. The JMX ObjectName for this MBean can be queried by the
administrative tool using the getInstallerConfigurationMBean() method.
• Check if already installed. The administrative tool can check if the component associated with the
InstallerMBean is already installed by using the isInstalled() method.
• Uninstall the component. The administrative tool can uninstall the component associated with the
InstallerMBean by invoking the uninstall() method.
6.4.2.1 Installation Process
The installation process involves the following two interactions with an administrative tool:

Management
• Loading of the installer using the InstallerServiceMBean. This results in the creation of an
InstallerMBean for the component.
• Running the installer, using the InstallerMBean created above.
Optionally, the tool may interact with an installation extension MBean, installed during the above process.
These steps are elaborated upon in the following subsections.
6.4.2.1.1 Loading the Installer
When the InstallerServiceMBean.loadNewInstaller() method is called, the JBI
implementation MUST perform the following steps. A failure of any one of the steps will cause the entire
installation to be aborted, leaving the JBI environment in the same state it was in before the installation was
attempted.
1. Prepare installation context. When an installer MBean is created, the installation package ZIP file MUST
be expanded into an install root. This root is used throughout the lifetime of the component, and MUST be
located in a file system. Class path elements (from the jbi.xml installation descriptor) refer to items in the
install root. The JBI implementation MUST create an InstallationContext object, initialized to
provide the following data:
• Installation root, as a String containing the root’s full directory path name.
• Bootstrap class name, as given in the installation descriptor.
• Bootstrap class path, as given in the installation descriptor.
• Component name, as given in the installation descriptor.
• Installation Extension Data. A DOM fragment containing the installation extension data present in the
installation descriptor. If there are no such data in the descriptor, the fragment MUST be null.
2. Prepare Bootstrap class loader. The JBI implementation MUST create a class loader that provides access
to the bootstrap class path declared in the installation package descriptor. This class loader is described in
detail in chapter 7, “Component Framework.”
3. Initialize Installer. Using the above class loader, the JBI implementation MUST create an instance of the
bootstrap class, as declared in the installation descriptor. It MUST initialize the bootstrapper, by invoking
its init() method, passing it the installation context prepared in step 1. At this point the bootstrap code
provided by the component may optionally register an installation extension MBean, using the JMX server
provided by the component context.
4. Create Installer MBean. After the bootstrap init() call, the JBI implementation MUST create and
register an InstallerMBean for the component. Note that the InstallerMBean will need references
to the bootstrap loader object and the installation context to complete the installation.
6.4.2.1.2 Customized Installation
The administrative tool, after loading the installer as detailed in section 6.4.2.1.1, receives a JMX object name
for the InstallerMBean created for the component. The administrative tool must use the
InstallerMBean’s getInstallerConfigurationMBean() method to query for the existence of the
optional InstallerConfigurationMBean. If this does exist, the customization of the installation must
be done, using the InstallerConfigurationMBean BEFORE the installer is run by the administration
tool.
6.4.2.1.3 Run Installer
The administrative tool, after loading the installer as detailed in section 6.4.2.1.1, receives a JMX object name
for the InstallerMBean created for the component. The installation is completed by the administration tool
invoking the component’s InstallerMBean install() method. The JBI implementation MUST
perform the following processing steps to complete the installation.

Management
1. Invoke the bootstrap object’s onInstall() method.

2. Invoke the bootstrap object’s cleanUp() method. At this point the bootstrap can deregister any
previously registered MBeans.
A successful invocation of install() returns the JMX object name of the component’s
ComponentLifeCycleMBean, which is used to control the running state of the component. See
“Component Life Cycle” on page 74.
6.4.3 Component Uninstallation

Component uninstallation is used to reverse installation, using the InstallerMean created as detailed in
section 6.4.2. Note that the instance of the bootstrap class used for uninstallation is not guaranteed to be the
same one that was used during component installation.
Note that if the bootstrap’s init() method registers an extension MBean, the bootstrap’s cleanUp()
method should deregister it, just as it does during installation processing, described above.
6.5 Component Life Cycle

Each component has a life cycle that:
• begins when the component is installed, using the InstallationServiceMBean. This puts the
component into the “installed” state. All execution states of the component are considered to be substates of
the “installed” state.
• is controlled through a ComponentLifeCycleMBean, and (optionally) through a life cycle extension
MBean (for custom life cycle substates)
• is implemented by the component, using the ComponentLifeCycle SPI. This is detailed in the
“Framework” chapter.
The JBI implementation provides the ComponentLifeCycleMBean, which interacts with the component’s
SPI implementation to control the life cycle state of the component.

Management
Each installed component has a minimal life cycle, as defined here. This is illustrated below. The minimal life
Figure 25 Component Life Cycle State Diagram
cycle is modelled by two JBI MBeans: the InstallerMBean, which controls whether or not the component
is installed in the JBI system (i.e., in the installed state, as illustrated above), and the
ComponentLifeCycleMBean, which controls the component’s more conventional start/stop life cycle. The
component can extend the conventional life cycle by providing a life cycle extension MBean, which provides
additional life cycle states. Figure 26 illustrates this by adding a single “paused” substate to the standard

Management
“Started” state. This extra substate is accessed through use of a “pause” control supplied by the extension
MBean.
Figure 26 Example Extended Component Life Cycle State Diagram
The ComponentLifeCycleMBean and the life cycle extension MBean, if any, are the means by which a
management tool asks that the component change its running state. The component’s implementation of the
ComponentLifeCycle interface provides the actual logic to perform the state transitions that can be
commanded by administrative tools by means of these MBeans. The JBI implementation is responsible for the
following:
• It MUST persist the basic execution state the component is in.
• It MUST sequence the invocations of ComponentLifeCycle methods to assure legal transitions
through the basic execution states allowed. For example, if the start() MBean control is invoked by a
management tool on a component that is in the shutdown state, the implementation MUST, in sequence,
invoke the ComponentLifeCycle’s init() and start() methods. See the “Framework” chapter
for details on these component life cycle methods.
Note that on restart of the JBI environment, the JBI implementation MUST attempt to restore all components to
their previous standard running state. If a component wishes to instead restart in a different, extended substate
of the “Started” state, it must supply its own mechanisms to persist the extending running state, and restore it
during restart of the component by JBI. All life cycle extensions are considered substates of the Started state;
see the “Framework” chapter for details.
Instances of the component Bootstrap implementation MUST have their init() method called before it
can be used. Different instances of Bootstrap can be used during the extended life cycle of a component.
When the JBI implementation is finished with a Bootstrap instance, it MUST call the instance’s
cleanUp() method.

Management
The sequence of interactions between the participants collaborating in the installation process is illustrated in
the figure below. This includes use of a configuration extension MBean. This diagram depicts the logical order
Figure 27 Installation Process Message Sequence Diagram (with Extension MBean)
of operations. JBI and component implementations may vary the sequence, as long as the logical ordering
shown is preserved.
The process is driven by the administrative tool. Using the InstallationServiceMBean, the tool creates
a new InstallerMBean instance. The installer uses this new installer MBean to access the extension
MBean, in order to configure the Bootstrap object before installation continues. Finally, the tool starts the
install process proper: the InstallerMBean exploding the contents of installation package, and invoking the
Bootstrap object’s onInstall() and cleanUp() methods, in that order.
Note that registration and deregistration of the extension MBean is meant to depict use of the MBean server;
this is omitted from the diagram for simplicity. Components may create and register the MBean in the
Bootstrap’s init() method, or in the getExtensionMBean method. In either case, the extension MBean
must be deregistered in the cleanUp() method.
Note also that the admin tool is not obliged to call the getInstallerConfigurationMBean() method
of the InstallerMBean, as shown above. This step may be skipped by the admin tool if need be. (The tool
could, for example, have prior knowledge that the installer doesn’t have such an MBean, or that the tool had no
way of dealing with such an extension MBean if it did exist.)
The “explode” step that the InstallerMBean performs on itself depicts the process of unpacking the
contents of the component’s installation archive into its assigned root directory.

Management
The uninstallation process is similar, and is depicted below. Note that the Bootstrap object creates, registers,
Figure 28 Uninstallation Process Message Sequence Diagram (with Extension MBean)
and deregisters the extension MBean. Also note that the Bootstrap object’s onUninstall() method is
called before the “clean up” step during uninstallation is done (the clean up step reverses the “explode” step
performed during installation). This is in contrast to the installation process, where the Bootstrap object’s
onInstall() method is invoked after the “explode” step. After this, the Bootstrap object’s cleanUp()
method is called, allowing the Bootstrap implementation to free any resources still allocated, such as the
registration of the extension MBean. Finally, the unloadInstaller() method is called on the installation
service MBean, at which time the implementation MUST register and clean up the installer MBean created at
the beginning of the sequence.
6.6 Deployment Service

The deployment service allows the administrative tool to deploy and undeploy service assemblies to and from
the JBI environment, and control the running state of those assemblies.
A deployment consists of a service assembly, as described in the section on “Service Assembly Packaging” on
page 70. The administrative tool requests deployment of an assembly by invoking the
DeploymentServiceMBean deploy() method, passing it a URL for the resource containing the service
assembly package. The package must conform to the requirements detailed in the section on “Service Assembly
Packaging”, else the deployment MUST fail (by throwing a java.lang.Exception) without attempting to
deploy any of the service units contained within the assembly.
Note that in the following description, a “duplicate” service unit is one that:
• has the same name as a service unit previously deployed to the component, and
• has the same contents as the service unit previously deployed to the component (the service units are
exactly the same length and have exactly the same binary contents).

Management
The JBI implementation MUST detect such duplicates. While it is an error for the administrator to deploy a
non-duplicate service unit that uses the same name as previously deployed service unit, it is not an error to
redeploy a duplicate service unit.
When a valid deployment package is received by the “deploy” method, the JBI implementation MUST provide
the following processing steps:
1. Validate the deployment package, ensuring that the deployment descriptor conforms to section 6.3.3. Also,
ensure that all service-unit artifacts are present in the package, and that all named target components are
installed in the JBI system.
2. For each <service-unit> in the <service-assembly> deployment descriptor:
• Unzip the service-unit artifacts archive, and place the result in file storage. (If the service-unit is deployed
to more than one component in the same deployment descriptor, the service unit MUST be copied such
that any changes to the deployment contents made by one component to the deployment artifacts do not
affect the other).
• Deploy the named service-unit to the named component. This is detailed in section “Service Unit
Deployment Processing” on page 79.
If any iteration (or iterations) of step 2 fails to successfully deploy the named service-unit to the named
component, the implementation MUST continue to deploy any remaining service units in the assembly. If all
service units of the assembly fail to deploy, a failure exception MUST be thrown. If at least one service unit
deployment succeeds, then any failures MUST be reported using the status return String of the
DeploymentServiceMBeans’s deploy() method. The format of this string is specified in section 6.9.
If the service-unit deployment is a duplicate, deployment MUST be skipped, without being considered a
deployment failure. Thus, redeployment of an assembly should succeed, but not disturb the existing
deployments.
The DeploymentServiceMBean is also used to control the life cycle of service assemblies; see section 6.8.
6.6.1 Service Unit Deployment Processing

Individual service units are deployed as detailed in this section. As noted above, the service unit artifacts are
persisted by the JBI implementation. For each service unit, the JBI implementation MUST perform the
following actions for non-duplicate service-unit deployments only. This MUST be performed in the same order
as the service units are declared in the service assembly descriptor.
1. The ServiceUnitManager interface for the target component MUST be located. Note that this is
supplied by the component, not the JBI implementation, and is located by the JBI implementation by
calling the component’s Component.getServiceUnitManager() method.
2. Resources are allocated by the implementation for the service unit, including, but not limited to, file storage
for the service unit deployment.
3. The implementation MUST unzip (“explode”) the contents of the service unit into the root directory of the
assigned file storage for the service unit.
4. The implementation MUST deploy the service-unit artifacts to the component, using the above interface’s
deploy() method, supplying it the service-unit name, as declared in the deployment descriptor, and the
file path name to the root of the persisted artifacts of the service unit.
At this point, the service unit deployment is ready for its normal life cycle control, as detailed in section 6.7.
When first installed, a service unit (and the service assembly that it is a part) MUST be in the “Shutdown” state.

Management
6.6.2 Service Assembly Undeployment Processing

A service assembly must be in the Shutdown state before it can be undeployed. Service assemblies are
undeployed using the DeploymentServiceMBean’s undeploy() method, which takes as a parameter
the unique name of the service assembly that is to be undeployed. For each service unit in the indicated service
assembly, the JBI implementation MUST perform the following actions. This MUST be performed in the
reverse order of the declaration of the service units in the service assembly descriptor.
1. The ServiceUnitManager interface for the target component MUST be located. Note that this is
supplied by the component, not the JBI implementation, and is located by the JBI implementation by
calling the component’s Component interface implementation getServiceUnitManager() method.
2. The implementation MUST undeploy the service-unit artifacts from the component, using the above
interface’s undeploy() method, supplying it the service-unit name, as declared in the deployment
descriptor, and the file path name to the root of the persisted artifacts of the service unit.
3. The implementation may clean up resources associated with the service unit deployment, including the file
store under the root directory for the service unit.
6.6.3 Connection Metadata Handling

A service assembly may include connection metadata: data that describe mappings from consumer-provided
service addresses to service provider endpoint addresses. These mappings affect how the NMR routes message
exchanges between consumers and providers, and is discussed in the “Normalized Message Router” chapter.
This facility is useful for tools that compose new service assemblies, manipulating existing service units. This
facility is also useful for administrative purposes.
A JBI implementation MUST use the connection metadata, supplied in the connection section of the service-
assembly deployment descriptor, to create service connections: mappings that MUST be used by the JBI
implementation when performing normalized message routing. (The processing involved is described in the
“Normalized Message Routing” chapterT)
Service connections are defined logically as structures that contain two addresses:
• A consumer address. This is an address that will be provided by a service consumer. This can take one of
two forms:
• Service type name. The consumer specifies the desired service type, using its interface name.
• Service endpoint name. The consumer specifies the desired service endpoint, using its fully qualified
name.
• A provider endpoint address. This is the address of the actual provider to route exchanges sent to the
consumer address.
6.6.3.1 Link Types
Normalized message routing serves to route message exchanges from the initiating consumer to a provider. In
some cases a consumer may wish to control how routing for an exchange it is initiating can be influenced by
service connections. This is termed the provider link type. There are three types of provider linking possible:
• Standard links. The NMR performs its normal routing, including application of service connections.
• Hard links. The consumer specifies the endpoint of a provider directly, and the routing should not be
affected by service connections. In other words, the consumer is asserting that the endpoint address given
must exist as an internal endpoint.
• Soft links. The consumer specifies the endpoint of a provider using an indirect address. In this case the
consumer provides a “false” (non-existent) endpoint. This type of link is an assertion by the consumer that
the address given must be resolved using a service connection, and that it is an error if the named endpoint

Management
exists as an internal endpoint.

6.6.3.2 Service Units and Normalized Message Routing
A service unit contains metadata about the static services it provides and consumes. These data are primarily for
the use of tools used to compose (and recompose) service assemblies. There is one particular attribute of
consumed services declared by a service unit that affects how links are handled by the JBI implementation. This
is the consumes element’s link-type attribute. This is used to specify a service unit’s consumer service
link type for consumption of the given service endpoint name. The various link types are defined in section
6.6.3.1, above.
The JBI implementation MUST, during deployment of a service unit, read the service unit deployment
descriptors, and gather all link-type declarations. These MUST be used to affect normalized message
routing decisions for message exchanges initiated by the component to which the service unit is to be deployed,
as detailed in the “Normalized Message Routing” chapter. The implementation MUST gather and put into effect
all service connection and link type information from the deployment before the service assembly is started.
The implementation MUST suspend all service connections from a service assembly after the service assembly
is stopped or shutdown.
6.7 Service Unit Life Cycle

Each service unit deployment has a life cycle, allowing it to be stopped, started, etc. A state diagram depicting
this is shown in Figure 29. The exact interpretation of this life cycle model is component-dependent, but in
Figure 29 Service Unit (SU) Life Cycle State Diagram
general components should interpret the Started state of a deployment as starting the provision and consumption
of services related to the deployment itself, while the Stopped state means that consumption of services have
ceased, and the Shutdown state means that both provision and consumption of services have ceased. The life
cycle state of a deployment is referred to as its running state.
Groups of service unit deployments are started in two phases, to assure orderly start-up of the JBI system. On
start or restart of any group of deployments, a JBI implementation MUST call init() for all service unit
deployments in the group before calling start() on any that are to be started.

Management
JBI implementations MUST retain the running state of all service unit deployments, such that the system can be
restarted from a shutdown or crash, and all deployments will be restored to their previous running state. During
component restart, the implementation MUST perform the following to restore a service unit to its previous
state:
• Started. The implementation MUST call init(), followed by start().
• Stopped. The implementation MUST call init() to restore a service unit to the stopped state.
• Shutdown. The implementation MUST call init() followed by shutDown() to restore a service unit
to the shutdown state.
In all cases of state restoration, the implementation MUST call init() for all service units in the group being
restored before any other life cycle methods for service units in the group are called.
6.8 Service Assembly Life Cycle

Each service assembly has a life cycle, similar to the life cycle of the individual service units within the
assembly. A state diagram depicting this is shown in Figure 30. Individual service assemblies have their life
Figure 30 Service Assembly Life Cycle Diagram
cycle controlled by the administrative tool through the use of the DeploymentServiceMBean:
• start(serviceAssemblyName). This method MUST attempt to start each of the service units of the assembly
that is not currently in the Started state. If any of the units are in the Shutdown state, then the
implementation MUST first invoke init() for each of those service units, as required above in section
6.7.
• stop(serviceAssemblyName). This method MUST attempt to stop each of the service units of the assembly
that is currently in the Started state.
• shutDown(serviceAssemblyName). This method MUST attempt to shut down each of the service units of
the assembly that is not currently shutdown. For all service units are in the Started state, the implementation
MUST first stop each of those service units, before attempting to shut down any of the service units of the
assembly.

Management
When a failure to change the running state of any service unit occurs while processing the above management
commands, the failure MUST be reported in the returned status/result string (see section 6.9 for formatting
details).
Note that the running state of individual service units is controlled by using the ServiceUnitManager’s
life cycle controls for named service units. Access to each component’s ServiceUnitManager is described
in section 6.6.1.
6.9 MBean Status and Result Strings

Several JBI management bean methods require a String status / result code, used to convey the result of
performing the particular management task, including error information if it fails. This section defines the
format of such strings. Serialized XML documents that conform to the following schema are used, and passed
as Java strings, to convey the status and results of invocations of selected management controls on JBI-
implemented MBeans.
This approach has several advantages. By using XML, the problem of synchronized class definitions is avoided
in distributed scenarios that are typical when using JMX. In addition, XML is readily manipulated, allowing

Management
management tools to make good use of the information to act on the results, display error messages, log results,
etc.
default namespace = "http://java.sun.com/xml/ns/jbi/management-message"

start =
element jbi-task {
jbi-task-result
}
jbi-task-result =
element jbi-task-result {
frmwk-task-result,
component-task-result*
}
frmwk-task-result =
element frmwk-task-result {
frmwk-task-result-details,
element is-cause-framework { "YES" | "NO"}?
}
component-task-result =
element component-task-result {
element component-name { xsd:NCName },
component-task-result-details
}
frmwk-task-result-details =
element frmwk-task-result-details {
task-result-details,
element locale { text }
}
component-task-result-details =
element component-task-result-details {
task-result-details
}
task-result-details =
element task-result-details {
element task-id { text },
element task-result { "SUCCESS" | "FAILED" },
element message-type { "ERROR" | "WARNING" | "INFO" }?,
element task-status-msg { msg-loc-info }*,
exception-info*
}
msg-loc-info =
element msg-loc-info {
element loc-token { text },
element loc-message { text },
element loc-param { text }*
}
exception-info =
element exception-info {
element nesting-level { xsd:integer },
msg-loc-info,
element stack-trace { text }
}
Listing 21 Status/Result Schema (Relax NG)
The elements of the Schema must be used by components as follows:

• jbi-task is the document element, which, along with the document’s namespace, identifies this as a JBI
management task result/status report.
• jbi-task-result is used to report the results of the implementation’s execution of the task, and, optionally,
the result of the component’s part of executing the task. This latter feature will appear only if applicable
(the task involves interaction with a component, and the task proceeds to the point where that interaction
was started.)

Management
• frmwk-task-result is used to report the results of the implementation’s execution of the task. This includes
an optional element, is-cause-framework, which the implementation MUST set to “YES” in cases where
the JBI implementation is the cause of the task failing to execute.
• frmwk-task-result-details is used to contain a detailed task report, as well as locale information about the
report (supporting I18N/L10N).
• component-task-result is used to report results of interaction(s) with a component. This includes the
component’s unique name and details about the component task results. For example, this is used by the
component’s ServiceUnitManager implementation to return the results of deploy() and
undeploy().
• component-task-result-details is used to report task result details as performed by the component.
• task-result-details is used to report the task ID, result (SUCCESS or FAILED), and, optionally, a typed
(ERROR, WARNING, or INFO) message. Zero or more task status messages can be included (for dealing
with multiple interactions with components). Finally, optional exception information can be provided.
• msg-loc-info is used to report a message in the form of a format string and zero or more text parameters.
This structure supports I18N/L10N.
• loc-token is the message key for looking up localized text for the message
• loc-message is the default message. All messages must use the java.text.MessageFormat
patterns to define the message, and where parameters are placed within the message.
• loc-param. Zero or more parameters for the message.
• exception-info is used to report exceptions. It contains the following items:
• nesting-level. This indicates by integer value what the exception’s level was within a nested set of
exceptions.
• msg-loc-info is used to report the exception message value, as described above.
• stack-trace is used to report a stack trace at the point where the exception was thrown.
The following listing shows an example of a deployment error.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<jbi-task version = "1.0"
xmlns = "http://java.sun.com/xml/ns/jbi/management-message">
<jbi-task-result>
<frmwk-task-result>
<frmwk-task-result-details>
<task-result-details>
<task-id>deploy</task-id>
<task-result>FAILED</task-result>
<message-type>ERROR</message-type>
<exception-info>
<nesting-level>1</nesting-level>
<msg-loc-info>
<loc-token>JBI1009</loc-token>
<loc-message>Unable to deploy {1}. Missing {2} section in jbi.xml
</loc-message>
<loc-param>file://d/jbi/samples/1/sampleAU.jar</loc-param>
<loc-param>service-unit</loc-param>
</msg-loc-info>
<stack-trace>....</stack-trace>
</exception-info>
<locale>en</locale>
</task-result-details>
</frmwk-task-result-details>
<is-cause-framework>YES</is-cause-framework>
</frmwk-task-result>
</jbi-task-result>
</jbi-task>
Listing 22 Example Deployment Error Message String

Management
In this example, the error is caused by a malformed deployment descriptor discovered by the JBI
implementation (framework).
Components supply status/result strings as XML strings that conform to the component-task-result-details type
from the above schema. For example, the ServiceUnitManager.deploy() method returns such a status/
result string. The JBI implementation MUST combine the status/result strings supplied by components into the
the overall status/result document defined above.
6.10 Ant Script Support

JBI implementations MUST provide support for managing the system using the scripting language Apache Ant
1.5 (or newer) [Apache Ant]. This section details the mapping of the management functions provided through
JMX management beans to Ant tasks. The actual processing that occurs is defined elsewhere this chapter, where
the functions of the management beans are defined.
By providing a standard scripting language, JBI enables component vendors to supply scripts for performing
complex administrative tasks (such as component configuration) in a portable fashion.This also allows users to
move administrative and development scripts between JBI installations, regardless of the vendor of the
underlying JBI implementation.
Ant scripts are written using XML. Each task is defined syntactically as named XML attributes and XML
elements. Each task defines an element; nested elements are contained within the task element.
Writers of Ant scripts should promote portability of such scripts by supplying necessary Ant task parameters
explicitly, rather than depend on implementation-specific default values. Parameterization of scripts, using Ant
properties, is a good practice.
6.10.1 Including Task Definitions

The Ant task definitions that bind the Ant task names defined in this specification to the classes that implement
the tasks must be included in a portable fashion. Ant offers several alternatives in this regard, and so leaves it to
implementations how this is to be accomplished in a particular Ant installation.
6.10.2 Exception Handling

When a JBI Ant task would end by throwing an exception, the implementation MUST wrap the exception in an
Ant BuildException, and end the task by throwing that. Remote (JBI) failures must be reduced to the root
cause (the JBIException); exception chains created by implementation features (for example, JMX
remoting) must not appear in the exception wrapped by the Ant BuildException.
6.10.3 Error Reporting

Ant’s standard error reporting mechanism must be used when a JBI task fails by throwing an Ant
BuildException.
6.10.4 Error Suppression

All JBI Ant tasks include an optional attribute, “failOnError”, which defaults to true. If this attribute’s
value is false, the task must not throw an Ant BuildException.
6.10.5 Remote Access to JBI Environment: URL Template

The Ant tasks specified in the following section have attributes for specifying the host name and port number

Management
used to remotely access the JBI environment targeted. This does not provide a full URL for accessing the JBI
environment; the implementation MUST provide a means for specifying a template that is used to construct the
URL, which is implementation specific. The reference implementation, which uses JMX connectors, provides
for this need in two ways:
• Using a system property:
com.sun.jbi.tools.remote.jmx.url = service:jmx:rmi:///jndi/rmi://{0}:{1}/management/rmi-jmx-connector
• Using an Ant property:
jbi.default.url=service:jmx:jmxmp://{0}:{1}
where {0} is replaced with the “host” attribute value and {1} is replaced with the “port” attribute value.
6.10.6 Ant Tasks

The following subsections define JBI Ant tasks that provide access to management functions equivalent to
those defined for specific JBI MBeans. For details on the specific functions, including errors reported, please
refer to the appropriate MBean documentation.
6.10.6.1 Task: jbi-install-component
This task installs a JBI component (a service engine or binding component) into a JBI environment. This task
takes optional installation configuration parameters as name/value pairs for setting the attributes of the
InstallerConfigurationMBean during the installation. The task takes the configuration parameters as
optional nested <param> elements, or using an optional params attribute if the parameters are in a file. The
Attribute Description Required?

host Target server on which JBI Environment is running. Defaults to No
"localhost"
port JMX Remote port on the target server. Default value is No
implementation-specific.
username User name for security. Defaults to "". No
password Password for security. Defaults to "". No
file Fully qualified installation file path name. The file contains a Yes
component installation package, as described in “Installation
Packaging” on page 69.
failOnError Signal task failure to Ant. Defaults to "true". No
params Location of a text file (e.g. configuration.properties) that contains No
name/value pairs corresponding to the properties of the
configuration MBean.
Table 6 Attributes for task jbi-install-component
installation process provided by this task MUST both load and install the component.
6.10.6.1.1 Nested Element <param>
This nested element is an optional child element containing an installation configuration parameter which will
be passed to the install task. Multiple parameters require multiple <param> elements, one per parameter. This
element takes a name/value pair for setting the property of the InstallerConfigurationMBean
implemented by the Installer of the component.
Note that the attribute name value is case sensitive. For example, if the configuration MBean has a attribute Foo
as a “setFoo” not as a “setfoo”, then the name attribute value for the param element must be “Foo”. Passing the

Management
name attribute value as “foo” will result in a property not found error.

name Name of the property on the InstallerConfigurationMBean. Note Yes.
that the attribute name is case sensitive. For example, if the
ConfigurationMBean has a attribute Foo as a “setFoo” not as a “setfoo”, then
the name attribute for the param element should be “Foo”. Passing the name
attribute as “foo” will result in a property not found error.
value Value of the property to be set Yes.
Table 7 Attributes for task jbi-install-component / param
6.10.6.1.2 Attribute params

This attribute is optional, indicating the location of a file containing installation configuration parameters which
will be passed to the install task. This attribute specifies the location of a file that contains a set of name/value
pairs corresponding to the attributes of the InstallerConfigurationMBean implemented by the
Bootstrap implementation of the component. The implementation MUST read the indicated file as a
java.util.Properties file, and use each named property to set equivalent attributes of the installer extension
MBean.
If the jbi-install-component element contains a <param> child element, as well as a params
attribute, the implementation MUST combine the two parameter lists, giving precedence to those defined in the
properties file indicated by the params attribute. This precedence rule allows tools to generate properties files
that can customize standard Ant scripts for performing installation of components.
6.10.6.1.3 Example
Assume a component has a configuration MBean as shown below. An Ant task that installs the component and
MyConfigMBean {
setFoo1(String value);
setFoo2(String value);
}
Listing 23 Example Configuration MBean
configures it using the example MBean is shown below. This example uses script-supplied parameters to


<jbi-install-component host = "localhost" port="7890"
file = "${my.dev.dir.path}/bpel-engine.zip" />
<param name="Foo1" value="bar1" />
<param name="Foo2" value="bar2" />
</jbi-install-component>
Listing 24 Example use of jbi-install-component task using param elements for configuration data
provide the configuration data. Alternatively, an external file can be used to supply the configuration data. This

Management
is shown below.


<jbi-install-component file="dir/component.zip" params="dir/params.properties"
port="555"/>
where the contents of the dir/params.properties file are:
Foo1=bar1
Foo2=bar2
Listing 25 Example use of jbi-install-component task using configuration data supplied by an external file.
6.10.6.2 Task: jbi-uninstall-component

This task uninstalls a previously installed JBI component (service engine or binding) from the JBI environment.

"localhost"
name Name of the JBI component in the JBI Environment. This is the Yes
unique name specified in the component’s installation descriptor.
Table 8 Attributes for jbi-uninstall-component task
6.10.6.3 Task: jbi-install-shared-library

This task installs a shared library into a JBI environment.

"localhost"
file Shared library installation file path/name. This file is a shared- Yes
library installation package, as described in “Installation Packaging”
on page 69.
Table 9 Attributes for jbi-install-shared-library task
6.10.6.4 Task: jbi-uninstall-shared-library

This task uninstalls a previously installed share library from a JBI environment.

host Target server on which JBI Environment is running. Defaults to
"localhost"
Table 10 Attributes of the jbi-uninstall-shared-library task

Management

name Name of the shared library in the JBI Environment. Yes.
Table 10 Attributes of the jbi-uninstall-shared-library task
6.10.6.5 Task: jbi-start-component

This task starts a particular JBI component (service engine or binding component) in a JBI environment.

"localhost"
name Name of the JBI component in the JBI Environment to start. Yes.
Table 11 Attributes of the jbi-start-component task
6.10.6.6 Task: jbi-stop-component

This task stops a particular JBI component (service engine or binding component) in the JBI environment.

"localhost"
name Name of the JBI component in the JBI Environment to stop. Yes.
Table 12 Attributes for jbi-stop-component task
6.10.6.7 Task: jbi-shut-down-component

This task shuts down a particular JBI component in a JBI environment.
Attribute Description Required

"localhost"
Table 13 Attributes for jbi-shut-down-component task

Management
Attribute Description Required

name Name of the Service Engine or Binding component in the JBI Yes
Environment.
Table 13 Attributes for jbi-shut-down-component task
6.10.6.8 Task: jbi-deploy-service-assembly

This task deploys a service assembly into a JBI environment.

"localhost"
file Fully qualified service assembly file path. The file should be Yes.
packaged according to the JBI service assembly packaging
specification, elsewhere in this chapter.
Table 14 Attributes for jbi-deploy-service-assembly task
6.10.6.9 Task: jbi-undeploy-service-assembly

This task undeploys a previously deployed service assembly from a JBI environment.

"localhost"
name Name of the service assembly that is in the JBI Environment Yes
Table 15 Attributes for jbi-undeploy-service-assembly task
6.10.6.10 Task: jbi-start-service-assembly

This task starts a particular service assembly in a JBI environment. The attributes for this task are listed below.

host Target service on which the JBI environment is running. Defaults to No
"localhost"
name Name of the service assembly that is in the JBI environment. Yes
Table 16 Attributes for jbi-start-service-assembly task

Management
6.10.6.11 Task: jbi-stop-service-assembly

This task stops a particular service assembly in a JBI environment. The attributes for this task are listed below.

"localhost"
Table 17 Attributes for jbi-stop-service-assembly task
6.10.6.12 Task: jbi-shut-down-service-assembly

This task shuts down a particular service assembly in a JBI environment. The attributes for this task are listed
below.

"localhost"
Table 18 Attributes for jbi-shut-down-service-assembly task
6.10.6.13 Task: jbi-list-service-engines

This task prints information about all of the Service Engines in a JBI environment. The attributes for this task
are listed below.

"localhost"
state Lists the Engines that are in the specified state. Without this No
parameter, list engines with all states. Valid states are: “shutdown”,
“started”, “stopped” (not case sensitive)
sharedLibraryName List the Engines that are dependent on the specified shared library No
Without this parameter, no shared library dependency is verified.
serviceAssemblyName List the Engines that have Service Units deployed to them as part of No
the Service Assembly deployed in the JBI Environment.
Without this parameter, no Service Assembly dependency is
verified.
Table 19 Attributes for the jbi-list-service-engines task

Management

serviceEngineName If supplied, only the named service engine is reported. If the engine No
doesn’t exist, an empty component-list report is given.
xmlOutput If supplied, set the given Ant property name value to the XML No
version of this listing task.
Table 19 Attributes for the jbi-list-service-engines task
If the xmlOutput attribute is specified, the task must produce an XML document conforming to the following
default namespace = "http://java.sun.com/xml/ns/jbi/component-info-list"

start = element component-info-list {
# version = "1.0" in this revision
component-info*
}
component-info =
element component-info {
attribute type { "service-engine" | "binding-component" | "shared-library" },
attribute name { text },
attribute state { "Shutdown" | "Started" | "Stopped" | "Unknown" },
}
Listing 26 Component List Information Listing XML Schema (Relax NG)
XML schema. If xmlOutput is not specified, an implementation-defined text format MUST be output. An
example of such an output is below. An Ant script to produce equivalent XML output, and the output itself is
-----------------------------------------
------------ Service Engines ------------
-----------------------------------------
Name: Test_engine1
State: Started
Description: Test engine with shared library.
Name: ant_test_engine2
State: Shutdown
Description: Yet another test engine.
Listing 27 Example Service Listing
show in the next two listings.
jbi-list-service-engines xmlOutput="jbi.output"/>


<echo message="${jbi.output}"/>
Listing 28 Example Ant Script fragment to List Service Engines as XML Output

Management

<component-info-list xmlns="http://java.sun.com/xml/ns/jbi/component-info-list"
version="1.0">
<component-info type="service-engine" name="Test_engine1" state="Started">
<description>Test engine with shared library.</description>
</component-info>
<component-info type="service-engine" name="ant_test_engine2" state="Shutdown">
<description>Yet another test engine.</description>
</component-info>
</component-info-list>
Listing 29 Example Service Engine Listing as XML Output
The schema MUST be used by the implementation as follows:

• component-info contains information about a single component. It contains:
• type. This indicates the component type.
• name. The unique component name, as supplied by its installation descriptor.
• state. The execution state of the component. Note that extension states are substates of the “Started”
state, and that if the component is in an extended state it will show as “started” in this attribute.
• description. The description of the component, as supplied by its installation descriptor.
• optional extension elements. This area allows the implementation to provide extra, implementation-
specific component information.
6.10.6.14 Task: jbi-list-binding-components
This task prints information about the binding components installed in a JBI environment. When the

"localhost"
username User name for security. No
password Password for security. No
state Lists the Bindings that are in the specified state.With out this No
parameter, list Bindings with all states. Valid states are: “shutdown”,
“started”, “stopped” (not case sensitive)
sharedLibraryName List the Bindings that are dependent on the specified shared library. No.
Without this parameter, no shared library dependency will be
verified.
serviceAssemblyName List the Bindings that have Service Units deployed to them as part No
of the Service Assembly deployed in the JBI Environment. Without
this parameter, no Service Assembly dependency is verified.
bindingComponentName If supplied, only the named binding component is reported. If the No
binding doesn’t exist, an empty component-list report is given.
Table 20 Attributes for the jbi-list-binding-components task
xmlOutput attribute is specified, the format of the output must conform to the schema described in Listing
26, above. If the xmlOutput attribute is not specified, JBI implementations are free to format non-XML
output as they wish.

Management
6.10.6.15 Task: jbi-list-shared-libraries

This task prints information about all shared libraries installed in the JBI environment. When the xmlOutput
attribute value is specified, the format of the output must conform to the schema described in Listing 26, above.

"localhost"
componentName List the shared libraries that the component depends on. Without No.
this parameter, all the shared libraries in the JBI Environment are
displayed.
sharedLibraryName If supplied, only the named shared library is reported. If the shared No
library doesn’t exist, an empty component-list report is given.
Table 21 Attributes for the jbi-list-shared-libraries task
JBI implementations are free to format non-XML output as they wish.

6.10.6.16 Task: jbi-list-service-assemblies
This task prints information about service assemblies deployed in a JBI environment. If the value of the

"localhost"
state Lists the service assemblies that are in the specified state.With out No
this parameter, list service assemblies with all states. Valid states
are: “shutdown”, “started”, “stopped” (not case sensitive)
componentName List the service assemblies that has service units deployed to this No
component. Without this parameter, all the service assemblies that
are deployed in the JBI Environment will be displayed.
serviceAssemblyName If supplied, only the named service assembly is reported. If the No
service assembly doesn’t exist, an empty service-assembly-list is
reported.
Table 22 Attributes of jbi-list-service-assemblies task
xmlOutput attribute of the task is specified, the format of the must conform to the schema described in

Management
Listing 30, below. If xmlOutput is not required, the implementation is free to use any format for the output.
default namespace = "http://java.sun.com/xml/ns/jbi/service-assembly-info-list"

start = element service-assembly-info-list {
# version is 1.0 in this revision of JBI
service-assembly-info*
}
service-assembly-info =
element service-assembly-info {
attribute state { "Started" | "Stopped" | "Shutdown" | "Unknown" },
service-unit-info+,
}
service-unit-info =
element service-unit-info {
attribute state { "Started" | "Stopped" | "Shutdown" | "Unknown" },
attribute deployed-on { text },
}
Listing 30 Service Assembly Listing XML Output Schema (Relax NG)
This schema MUST be used by the implementation as follows:

• service-assembly-info-list. This contains a list of information elements about zero or more service
assemblies, as returned by the query task invoked.
• service-assembly-info. This element contains information about a particular service assembly, including
the service units which constitute the service assembly.
• name. The unique name of the service assembly, as assigned by the service assembly’s deployment
descriptor.
• state. The execution state of the service assembly.
• description. The description of the service assembly, as given in the service assembly’s deployment
descriptor.
• service unit information. Information about all of the service units that are contained in the service unit
described.
• extension elements. Optional, implementation-specific information about the service assembly.
• service-unit-info contains information about a particular service unit, which is part of the service assembly
described by the XML element within which it is contained.
• name. The name of the service unit, as assigned by the service assembly’s deployment descriptor.
• state. The execution state of the service unit.
• deployed-on. The unique name of the component to which the service unit was deployed.
• description. The description of the service unit, as given in the service assembly’s deployment
descriptor.
• extension elements. Optional, implementation-specific information about the service unit.

CHAPTER 7
Component Framework
JBI components (service engines and binding components) provide interfaces for the use of JBI, and use
interfaces provided by JBI. The major messaging and management contracts between JBI and a component
have already been discussed in previous chapters. The remaining contracts, known collectively as the
component framework, are detailed in this chapter.
JBI implementations provide an environment for components, in addition to that provided by the standard Java
(J2EE or J2SE) environment the implementation runs under. The JBI framework provides the following for the
use of components:
• Component installation context. This MUST be supplied to the component during component bootstrap
(installation customization). This provides access to JBI-provided resources and component installation
information during installation and uninstallation of a component.
• Component context. This MUST be supplied to the component during component initialization. This
provides access to JBI-provided resources during normal execution of the component.
• Class loading. JBI ensures that the class loader used to create instances of the component-supplied
Bootstrap and Component classes is set appropriately at both bootstrap- and execution-time. This
gives components access to a standardized class loader hierarchy, giving access to component, shared, and
JBI libraries.
• Error indication. Exception classes provide indication of JBI-specific errors to the component, and allow
the component to distinguish various error types.
In addition, components implement particular interfaces, to provide the following functions to JBI:
• Bootstrap. This provides extended installation (and uninstallation) configuration functions for the
component, beyond those JBI’s management functions already provide.
• Component. This interface provides JBI with methods to get the component’s life cycle interface, provide
service metadata, and get the component’s service unit manager.
• Component life cycle. This provides life cycle control of the component. This is utilized by the
ComponentLifeCycleMBean, as described in the “Management” chapter.
• Service unit manager. This provides deployment and life cycle control for service units deployed to the
component. This is an optional interface; components that do not support deployment need not supply a
service unit manager.
These component-supplied services are related to management activities; to fully understand how these services
are used please see the “Management” chapter.

Component Framework
7.1 Component-Supplied Management Functions
7.1.1 Bootstrapper
Installation of components is handled largely by the JBI management system (see the “Management” chapter
for details), which will copy the installation image to the file system of the JBI instance. The process of
installing (and the reverse, uninstalling) a component MAY be customized by the component. This allows
further installation processing beyond the simple copying of binary images that the management system
provides. For example, creation of database tables may be performed by a component’s bootstrap.
The component MUST provide, as part of its installation package, the fully-qualified name of a class that
implements the Bootstrap interface. (The installation package is specified in the “Management” chapter.)
The implementation MUST create and initialize (by calling Bootstrap.init()) an instance of the
Bootstrap class specified in the installation package before installing or uninstalling the component. This
process is detailed in the “Management” chapter.
7.1.2 Component Interface

Each component MUST supply an implementation of the Component interface. The implementation class
name is supplied to the management system using the installation descriptor. This descriptor is described in the
“Management” chapter.
The component interface functions as a single point for the JBI implementation to query the other component-
supplied interfaces described in this chapter, as well as metadata for component-supplied services. The
component interface provides access to:
• The component’s life cycle implementation, as described below.
• The component’s service unit manager. This is provided by components that support deployment; those that
do not must return null. It is RECOMMENDED that the component return the same instance of the
service unit manager every time its getServiceUnitManager() method is called.
The JBI implementation MUST obtain an instance of the component’s implementation of this interface AFTER
the component is installed, in order to further manage the component. This is accomplished by creating an
instance of the javax.jbi.component.Component as follows:
• the class name MUST be the component-class-name as declared in the component’s installation
descriptor (as described in the “Management” chapter), and
• it MUST be created using the component class loader (see “Execution Class Loader” on page 105 for
details).
The JBI implementation MUST create only one instance of the Component implementation at component
start-up time (after installation), or when restarting a previously installed component.
7.1.3 Component Life Cycle

Each component MUST supply an implementation of the ComponentLifeCycle interface. This is accessed
by JBI through the Component interface.
Note that this life cycle is distinct from the life cycle exposed to administrative tools, via the
ComponentLifeCycleMBean. The JBI implementation of the MBean MUST use the
ComponentLifeCycle interface to make required changes to the state of the component. See the
"Management" chapter for details on the component life cycle MBean.
After installation, the component is ready for conventional life cycle control. A component's basic life cycle

Component Framework
states, and transitions between states, are depicted below. Note that the “Paused” and “Running”states illustrate
Figure 31 Component Life Cycle State Diagram with Extension Substate
extended life cycle states that are an extension of the basic JBI life cycle states. All extended states are substates
of the standard “Started” state.
When first installed (as described in the “Management” chapter), the component is placed in the “Shutdown”
state. Before using the component-supplied services beyond the bootstrap, the implementation must obtain and
initialize the component’s life cycle implementation. This MUST be accomplished by using the component’s
implementation of javax.jbi.component.Component, as discussed above in “Component Interface”.
Using the component’s Component implementation, the JBI implementation MUST obtain the component’s
ComponentLifeCycle object.
When the LifeCycleMBean.start() method of the component is invoked (see the management chapter),
and the component is in the “Shutdown” state, the JBI implementation MUST call the component’s life cycle
init() method, passing to it a valid component context, followed by a call to the life cycle start() method, as

Component Framework
illustrated below. Subsequent calls to start(), from the “Stopped” state, MUST NOT cause the JBI
Figure 32 Initial Component Start Message Sequence
framework to call the init() method. Subsequent starts without an intervening stop and shut down behave as
shown below.
Figure 33 Component restart message sequence diagram
The JBI implementation MUST retain the Component implementation object created during the initial start
(or whenever it is first needed). The retained object is used to access the component’s life cycle implementation,
as well as other component information.
7.1.3.1 System Restart
The term system restart refers to the situation when the JBI system is restarted after a system shutdown or crash.
The JBI implementation MUST persist the running state of each component, such that, upon system restart, the
implementation will attempt to restore each component to its previous running state.
All component extended states are considered substates of the Started state. If a component must restore itself to
an extended state on system restart, it is responsible for persisting its state information, and, upon being
successfully restarted in the Started state, restore itself to the extended substate needed.
Component Framework
7.1.4 Service Unit Management

Each component can OPTIONALLY supply a service unit manager, in the form of an implementation of the
ServiceUnitManager interface. The absence of such a manager object implies that the component does
not expect deployment of Service Units (SUs).
The JBI implementation MUST call the ServiceUnitManager methods during service deployment, as
described in the “Management” chapter.
7.2 JBI-Supplied Environment Features
7.2.1 Component Context

The ComponentContext interface serves to allow components to query JBI-supplied aspects of the
execution environment the component is running in. This context is given to the component life cycle interface
using the init() method. The life cycle interface is described in detail in the “Management” chapter.
The execution context MUST make the following items available to the engine or binding:
• Component Name. The unique name assigned to the component at installation time.
• Installation Root. The installation root directory of the component.
• Workspace Root. The root directory of a “scratch pad” directory for use by the component. This is the root
of a file space that is reserved for use by the component, which it can use for any purpose.
• MBean Naming Service. A service that provides methods to generate JMX MBean Object Names for any
MBeans provided by the component.
• MBean Server. The JMX MBean server used to register all MBeans in the JBI system.
• Naming Context. A JNDI naming context for the use of the components.
• Delivery Channel. This allows the engine or binding to interact with the normalized message router. See
the “Normalized Message Router” chapter for details.
• Endpoint Activation/deactivation. This allows components to declare that endpoints provided by the
component are available to consumers within the JBI environment. See the “Normalized Message Router”
chapter for details.
• Endpoint Registration/deregistration. This allows bindings to declare external endpoints that are
available (or no longer available) for use as external endpoint references. See the “Normalized Message
Router” chapter for details.
In addition, the execution context provides the following functions for interacting with the NMR:
• Activate and deactivate endpoints for services offered by the component.
• Query available endpoints for a particular interface or service.
7.2.1.1 Querying Metadata
The ComponentContext interface allows JBI components to query the metadata of service providers in the
JBI system. This allows for dynamic service discovery and service provider selection.
• getEndpoints(). The implementation must return all endpoints providing a particular interface type.
• getEndpointsForService(). The implementation MUST return all of the endpoints provided by a
particular service.
• getEndpointDescriptor(). The implementation MUST return the metadata descriptor (WSDL) for
Component Framework
a given endpoint.
• getExternalEndpoints(). The implementation MUST return all of the external endpoints registered
that provide a particular interface type.
• getExternalEndpointsForService(). The implemenation MUST return all of the external
endpoints registered for a particular service.
Once a Descriptor for an endpoint is found, the service metadata (that is, the WSDL description of the
endpoint) can be retrieved using its getDescription() method, which returns a DOM representation of the
endpoint’s description.
7.2.1.2 Endpoint Activation and Deactivation
A JBI component that acts as a service provider MUST indicate to the NMR which endpoints it is currently
providing (a component can supply multiple endpoints). Such a component can dynamically (and arbitrarily)
activate and deactivate endpoints, using the following ComponentContext methods:
• activateEndpoint(serviceName, endpointName). This method is used by a component to
let the NMR know that the named endpoint is ready to process message exchanges. This MUST NOT be
called until the component is fully ready to process message exchanges destined for the named endpoint,
and the component's Component implementation is ready to supply service data about the endpoint.
• deactivateEndpoint(endpoint). This method is used by a component to let the NMR know that
the named endpoint is being withdrawn from service. The NMR MUST NOT allow initiators to invoke the
endpoint’s services after the endpoint is deactivated. Ongoing message exchanges will be permitted to
continue to completion.
7.2.2 Installation (Bootstrap)

The overall installation (bootstrap) process is described in the management chapter. As part of this process, the
JBI implementation supplies the component’s bootstrapper with an InstallationContext, which
provides the component’s bootstrap with environmental information to support installation and uninstallation
activities. (The installation context is supplied to the Bootstrap object’s init() method.)
7.2.2.1 Installation Context
To allow the component’s bootstrap implementation access to the key parts of the JBI environment that may be
needed during installation, the Bootstrap methods are passed a reference to a InstallationContext
interface. This context MUST provide access to the following:
• Component name. The unique name for the component, as provided in the installation descriptor.
• Component class name. The name of the class that implements the component SPI,
javax.jbi.component.Component, for this component. This can be read and written by the
component’s bootstrap. It is initially set to the component-class-name value supplied in the component’s
installation descriptor.
• Class path elements. A list of directories or jar files that will comprise the class path of the component
when it is executed. The class that implements the Component SPI must be accessible through this class
path. This can be read and written by the component bootstrap. This is initially set to the component-class-
path values supplied in the component’s installation descriptor.
• Component context. A JBI-global component context. It gives access to the items similar to the
component context given to a Component's life cycle init() method, but is global (shared by all
installation context instances). Only the getComponentName(), getInstallRoot(),
getMBeanNames(), getMBeanServer(), getNamingContext(),
getTransactionManager(), and getWorkspaceRoot() will be functional during installation.
Component Framework
Calling other methods MUST result in either null results or JBIExceptions.

• Installation root directory. The full path name of the directory into which this component is being
installed.
• Component installation descriptor. This provides access to the installation descriptor extension data from
the installation descriptor, jbi.xml, as described in the “Management” chapter description of the installation
packaging. This allows the bootstrap to access extended installation information.
Unless otherwise noted, these properties MUST be read-only.
The Bootstrap implementation MAY alter the class path element list items in the installation, using the
provided setter method.
7.2.3 Loggers
The ComponentContext supplied to a component implementation may be used by the component to create
standard java.util.logging.Logger instances. The getLogger() method takes two arguments: a
(possibly empty) suffix string, and a (possibly null) resource bundle name. The getLogger()
implementation MUST guarantee the following:
• The name of the logger is unique for the component. There will be no collisions between the name of the
created logger and loggers similarly created for other components, or with loggers used internally within
the JBI implementation itself.
• Calling getLogger with the same suffix argument, within the same component, will always return the same
logger instance.
The resource bundle name, if non-null, MUST be used by the implementation to construct the Logger
instance, thus enabling localized logging messages. The resource bundle MUST be loadable when using the
component’s class loader as the initiating loader (i.e., it must be available in the component’s own class path, or
in a shared library). See section 7.3, below, for details on class and resource loading in the JBI environment.
7.3 Class Loading

JBI implementations MUST provide class loaders that are used to create the initial, component-supplied
objects, at both installation- and execution-time, as specified in this section. This section defines how such class
loaders MUST behave, in order to assure a consistent class loading behaviour across all JBI
implementations.This is essential for component portability.
There are two separate phases in the lifetime of a component that require two different class loaders:
• Installation time. The component bootstrapper class must be implemented by the component and declared
in the component’s installation descriptor. Bootstrapper instances MUST be created by the JBI
implementation using a bootstrap class-loader as defined in this section.
• Execution time. The Component class (which implements the Component interface) MUST be
implemented by the component and declared in the component’s installation descriptor. The component
class MUST be created by the JBI implementation using an execution class-loader as defined in this
section.
Both types of class loaders provide the following:
• Platform classes and resources (if applicable)
• JBI classes
Component Framework
• Class-path accessible classes and resources:

• For the bootstrap execution class loader, this means the bootstrap-class-path declared in the component’s
• For the execution class loader, this means the class-path supplied by the InstallationContext for
the component, as described in “Installation (Bootstrap)” on page 102
The execution class loader adds one more item to be supported: shared libraries, which are described in section
7.3.2, below.
7.3.1 Class and Resource Loading Styles and Loader Ordering

Java 2 class loaders are used to load both Java classes and resources. An individual class loader has a “parent”
class loader, allowing multiple class loaders to be composed in an ordered hierarchy. The normal behaviour of a
class loader is to allow its parent to attempt to load a class (or resource) first. Only if the parent fails to do this
does the loader attempt to load the class itself. JBI terms this default behaviour as parent-first class loader
delegation.
Under some circumstances it is desirable to reverse this behaviour. JBI terms this self-first class loader
delegation. This is controlled by configuration data supplied by the installation descriptors for both components
and shared libraries. When a class loader is invoked, it will either delegate to its parent first, or itself first,
depending on the delegation style:
• parent-first: the loader MUST invoke the parent first. If the parent fails to load the class (or resource), the
loader MUST attempt to load it by itself.
• self-first: the loader MUST attempt to load the class (or resource) itself. It this fails, the loader MUST
invoke the parent.
Because of these two styles of class loader delegation, the order in which class loaders are invoked may not
correspond to the order in which they attempt to load a class or resource. If all class loaders use parent-first
delegation (the default), the order for attempts to load a particular class or resource will be opposite to the order
the class loaders are invoked. The first loader invoked is the component class loader.
When self-first delegation is the style used by a class loader, the loader MUST use parent-first delegation when
(and only when) loading classes whose fully-qualified class names begin with either "java." or "javax.".
When the first class loader in a hierarchy is “invoked” to load a class, it is referred to as the initiating class
loader. When a class loader actually defines (loads) a class, it is referred to as the defining class loader for that
class. Class loader ordering rules in this specification define the order of invocation; delegation style will affect
the actual order that loaders get a chance to define a class.
7.3.2 Shared Libraries

JBI components are loosely-coupled components that, at a minimum, interact only through the JBI
MessageExchange and NormalizedMessage interfaces. In some important use cases, this interaction
needs to be extended through NormalizedMessage properties, where the components have a shared
domain-specific set of classes used to read and write the message properties. For example, an EDI binding
component may wish to share a set of specialized class objects that represent an EDI document with a
specialized service engine that consumes such EDI documents. Given that the binding and engine are installed
separately, there is a need for the two components to share a common library that implements the shared classes,
and must also share the class loader for the library. This requires that the JBI environment provide support to
provide for such shared libraries and class loaders in the execution class loader’s hierarchy.
Component Framework
To facilitate sharing of class loaders between components in a controllable, predictable fashion that will not
adversely affect other system components, a specific class loading scheme for JBI environments is required.
This behaviour is defined in the following section, as part of the execution class loader.
7.3.3 Execution Class Loader

The execution class loader consists of a set of class loaders, which serve to load various classes and resources
needed by a component. These are described in this section. In addition, the execution class loader MUST
conform to the ordering rules defined in the following section.
JBI implementations MUST provide each component with a separate component class loader. The component
class loader MUST give access to the classes and resources in the component’s class path, as specified by the
component-class-path declaration in the component installation descriptor. The component class loader
MUST search the component class path in the order given in the installation descriptor, when searching for
either classes or resources. The component class loader MUST be the initiating class loader used by the JBI
implementation to create instances of the component’s declared Component class.
Shared-library class loaders provide access to shared libraries, which are installed separately from components,
with the intention that they be used by sets of components to allow sharing of Java objects based on non-
standard classes and interfaces. This creates a unique name space for the objects created from classes loaded
from the shared class loader. (Objects created from classes loaded by separate class loaders, even if from
identical .class resources, will not be considered to be of the same type by the Java run-time because the
class types came from separate name spaces.) A shared-library class loader MUST search the shared-library
class path in the order given in the installation descriptor.
The JBI class loader MUST be used to load the JBI classes. It MUST also provide an implementation of the
javax.xml.namespace.QName class (as defined in JAX-P 1.3), if not provided by the platform class
loader or the built-in class loader.
Some execution environments will provide a platform class loader, used to load shared platform classes. This is
appropriate for environments such as application servers, which provide other classes beyond the virtual
machine's built-in class loader.
7.3.3.1 Class Loading Ordering Rules
This section specifies the rules for ordering invocation of class loaders. The actual order used to search for a
class (or resource) will be affected by the delegation style of individual class loaders. The order specified here
refers to the order in which each class loader is invoked. This is distinct from the order in which each loader
attempts to define (load) the given class (or resource) itself.
1. The component class loader MUST be the initiating loader used when creating the component’s
Component class. Note that if the component is configured to use parent-first delegation (the default), the
component class loader will be the last one to attempt to define a class or resource.
2. The shared-library class loaders MUST be searched in the order they are declared in the component’s
3. The component class loader MUST treat the collection of all the component’s shared-library class loaders
as a single parent. That is, delegation to its parent must cause the shared-library class loaders to be used in
their specified order.
4. Each shared-library class loader must use the JBI class loader as its parent.
5. The JBI class loader MUST use the platform shared class loader as its parent, if applicable, otherwise it
MUST use the system class loader as its parent.
6. The parent of the platform shared class loader is unspecified by this specification (it is specified by the
appropriate platform specification).
Component Framework
The JBI class loader MUST always use parent-first delegation.

7.3.3.2 Delegation Style
Class loader delegation styles and behaviour are discussed in section 7.3.1, “Class and Resource Loading Styles
and Loader Ordering”, above. Self-first delegation, as described in section 7.3.1, for a component’s class loader
MUST be used if its installation descriptor specifies:
component-class-loader-delegation="self-first"
otherwise parent-first delegation MUST be used. Similarly, if a shared-library installation descriptor specifies
class-loader-delegation="self-first"
the shared library’s class loader MUST use self-first delegation, otherwise parent-first MUST be used.
7.3.3.3 Installation and Uninstallation of Shared Libraries
Shared libraries are installed (and uninstalled) using the Management InstallationServiceMBean. See
the “Management” chapter for details.
A shared library must be installed before a component can be installed that makes use of the shared library,
otherwise the component installation MUST fail. See the “Management” chapter, sections “Shared Library
Installation” and “Component Installation” for details.
Similarly, attempting to uninstall a shared library MUST fail if there is at least one installed component that
makes use of the shared library that is not in the "shutdown" state.
7.3.3.4 Component Viewpoint
There is no explicit API exposed by JBI that bindings and engines can use to examine or manipulate the JBI
class loading scheme. The JBI environment guarantees that the component’s Component implementation
MUST be constructed using the component class loader, as defined in section 7.3.3. This allows the component
to construct other objects using the component class loader implicitly, as detailed in The Java Virtual Machine
Specification, Second Edition [JVM 2], section 5.3.
7.3.4 Bootstrap Class Loader

The bootstrap class loader consists of a set of class loaders, which serve to load classes and resources needed
by a component during installation. These are described in this section. In addition, the bootstrap class loader
MUST conform to the ordering rules defined in the following subsection.
The JBI implementation MUST provide each component with a bootstrap class loader, that MUST always be
the class loader used to create instances of the component’s bootstrap class (as declared in the component’s
installation descriptor) when required. Note that the implementation is free to create more than one such
instance during the extended life cycle of the component, but MUST NOT use more than one such instance
concurrently.
The bootstrap class loader MUST give access to the classes in the component’s bootstrap class path, as
specified by the bootstrap-class-path declaration in the component’s installation descriptor. The
bootstrap class loader MUST search the bootstrap class path in the order given in the installation descriptor.
The JBI class loader is used to load the JBI classes. It MUST also provide an implementation of the
javax.xml.namespace.QName class (as defined in JAX-P 1.3), if not provided by the platform class
loader or the built-in class loader.
Some execution environments will provide a platform class loader, used to load shared platform classes. This is
appropriate for environments such as application servers, which provide other classes beyond the virtual
machine's built-in class loader.
Component Framework
7.3.4.1 Class Loading Ordering Rules

This section specifies the rules for ordering invocation of class loaders related to the bootstrap class loader. The
actual search order will be affected by the delegation style used by individual class loaders. The order specified
here refers to the order in which each class loader MUST be invoked. This is distinct from the order in which
each loader attempts to define the given class (or resource) itself.
1. The bootstrap class loader MUST be the initiating loader used when creating the component’s
Bootstrap class.
2. The bootstrap class loader MUST use the JBI class loader as its parent.
3. The JBI class loader MUST use the platform class loader as a parent, if applicable, otherwise it MUST use
the system class loader as its parent.
4. The platform shared class loader, if it exists, MUST use the system class loader as its parent.
The JBI class loader MUST always used parent-first delegation.
7.3.4.2 Delegation Style
Class loader delegation styles and behaviour are discussed in section 7.3.1, “Class and Resource Loading Styles
and Loader Ordering”, above. Self-first delegation, as described in section 7.3.1, for the bootstrap class loader
MUST be used if the component installation descriptor specifies:
bootstrap-class-loader-delegation="self-first"
otherwise parent-first delegation MUST be used.
7.4 Error Indication

Errors are indicated by use of Java Exceptions. All JBI exceptions MUST be based on
javax.jbi.JBIException, to allow component and administrative code to distinguish JBI-related error
conditions. The JBI exception types are:
• DeploymentException. This is thrown by the DeploymentServiceMBean to indicate, to an
administrative tool, that a deployment has failed. See “Management” for details.
• MessagingException. This is thrown by the NMR, indicating a variety of error conditions when creating,
manipulating, sending and receiving message exchanges and normalized messages. See “Normalized
Message Router” for details.
Note that the some JBI management bean (MBean) methods specify that they throw
java.lang.Exception objects. This is to avoid problems with remote JMX clients which otherwise would
require matching versions of JBI exception classes available in their classpath.
Component Framework
CHAPTER 8
Package
javax.jbi
Class Summary
Exceptions
JBIException110 JBIException is the top-level exception thrown by both JBI-supplied APIs and
component-provided SPIs.
JBIException javax.jbi
javax.jbi
JBIException
Declaration
public class JBIException extends java.lang.Exception
java.lang.Object
|
+--java.lang.Throwable
|
+--java.lang.Exception
|
+--javax.jbi.JBIException
All Implemented Interfaces: java.io.Serializable
Direct Known Subclasses: javax.jbi.management.DeploymentException141,

javax.jbi.messaging.MessagingException183
Description
JBIException is the top-level exception thrown by both JBI-supplied APIs and component-provided SPIs.
Member Summary
Constructors
JBIException(java.lang.String message)111
JBIException(java.lang.String message, java.lang.Throwable
cause)111
JBIException(java.lang.Throwable cause)111
Inherited Member Summary

Methods inherited from class Object
clone(), equals(Object), finalize(), getClass(), hashCode(), notify(), notifyAll(),
wait(long, int), wait(long, int), wait(long, int)
Methods inherited from class Throwable

fillInStackTrace(), getCause(), getLocalizedMessage(), getMessage(), getStackTrace(),
initCause(Throwable), printStackTrace(PrintWriter), printStackTrace(PrintWriter),
printStackTrace(PrintWriter), setStackTrace(StackTraceElement[]), toString()
javax.jbi JBIException
JBIException(String)
Constructors
JBIException(String)
public JBIException(java.lang.String message)
Creates a new instance of JBIException with the specified exception detail message.
Parameters:
message - the detail message for this exception
JBIException(String, Throwable)
public JBIException(java.lang.String message, java.lang.Throwable cause)
Creates a new instance of JBIException with the specified exception detail message and cause.
Parameters:
cause - Error or Exception which represents the cause of the problem (null if none, or if the
cause is not known)
JBIException(Throwable)
public JBIException(java.lang.Throwable cause)
Creates a new instance of JBIException with the specified cause.

Parameters:
cause is not known)
JBIException(Throwable)
CHAPTER 9
Package
javax.jbi.component
Class Summary
Interfaces
Bootstrap114 This interface is implemented by a JBI Component to provide any special processing
required at install/uninstall time.
Component116 This interface, implemented by component implementations, allows the JBI
implementation to query the component for various types of information.
ComponentContext119 This interface provides access to data needed by a JBI component about the JBI
environment in which it is installed, as well providing the means to allow the
component to inform the JBI environment about services provided by this component.
ComponentLifeCycle126 This interface must be implemented by a JBI component to provide initialization, start,
stop, and shutdown life cycle processing.
InstallationContext128 This context contains information necessary for a JBI component to perform its
installation/uninstallation processing.
ServiceUnitManager131 This interface defines component-supplied methods for managing service unit
deployments, and is implemented by the component.
Bootstrap javax.jbi.component
cleanUp()
javax.jbi.component
Bootstrap
Declaration
public interface Bootstrap
Description
This interface is implemented by a JBI Component to provide any special processing required at install/
uninstall time. The methods defined here are called by the JBI implementation during the installation (or
uninstallation) of the component that, among other things, supplies an implementation of this interface.
Initialization/cleanup tasks such as creation/deletion of directories, files, and database tables can be done by the
onInstall()115 and onUninstall()115 methods, respectively. This also allows the component to
terminate the installation or uninstallation in the event of an error.
After calling onInstall()115 or onUninstall()115 , regardless of outcome, the JBI implementation
must call the cleanUp()114 method afterwards. Similarly, if init(InstallationContext)115 fails
with an exception, the JBI implementation must call the cleanUp()114 method.
Component implementors should note that there is no guarantee that the same instance of its Bootstrap
implementation will be used during both install and uninstall operations on the component. Data that need to be
retained between installation-time and uninstallation-time must be persisted in such as fashion that a separate
instance of the bootstrap class can find them, despite component or system shutdown.
Member Summary
Methods
void cleanUp()114
getExtensionMBeanName()115
javax.management.Objec
tName
void init(InstallationContext installContext)115
void onInstall()115
void onUninstall()115
Methods
cleanUp()
public void cleanUp()
throws JBIException
Cleans up any resources allocated by the bootstrap implementation, including performing deregistration of
the extension MBean, if applicable.
This method must be called after the onInstall() or onUninstall() method is called, whether it succeeds or
fails. It must be called after init() is called, if init() fails by throwing an exception.
Throws:
javax.jbi.JBIException110 - if the bootstrap cannot clean up allocated resources.
javax.jbi.component Bootstrap
getExtensionMBeanName()
public javax.management.ObjectName getExtensionMBeanName()
Obtains the ObjectName of the optional installer configuration MBean. If none is provided by this
component, this method must return null.
This method must be called before onInstall() (or onUninstall()) is called by the JBI implementation.
Returns: ObjectName of the optional installer configuration MBean; returns null if there is no such
MBean.
init(InstallationContext)
public void init(javax.jbi.component.InstallationContext128 installContext)
throws JBIException
Initializes the installation environment for a component. This method is expected to save any information
from the installation context that may be needed by other methods.
If the component needs to register an optional installer configuration MBean, it MUST do so during
execution of this method, or the getExtensionMBean() method.
This method must be called after the installation root (available through the installContext parameter) is
prepared.
Parameters:
installContext - the context containing information from the install command and from the
component installation ZIP file; this must be non-null.
Throws:
javax.jbi.JBIException110 - when there is an error requiring that the installation be
terminated.
onInstall()
public void onInstall()
throws JBIException
Called at the beginning of installation of a component to perform any special installation tasks required by
the component.
This method must not be called if the init() method failed with an exception.
Throws:
javax.jbi.JBIException110 - when there is an error requiring that the installation be
terminated.
onUninstall()
public void onUninstall()
throws JBIException
Called at the beginning of uninstallation of a component to perform any special uninstallation tasks
required by the component.
This method must not be called if the init() method failed with an exception.
Throws:
javax.jbi.JBIException110 - when there is an error requiring that the uninstallation be
terminated.
Component javax.jbi.component
getLifeCycle()
javax.jbi.component
Component
Declaration
public interface Component
Description
This interface, implemented by component implementations, allows the JBI implementation to query the
component for various types of information. This includes:
• The component’s life cycle control interface.
• The component’s service unit manager, for handling deployments.
• A method for querying service metadata describing services provided by this component.
• “Policy” methods that are called by the JBI implementation to query if proposed matches of this component
to a provider (or consumer) are acceptable, according to this component’s policies.
• Endpoint reference (EPR) resolution. Some components will provide the ability to resolve EPRs (typically
binding components). This ability to resolve EPRs is used by JBI to facilitate resolution of EPRs received
by service consumers.
The name of the class that implements this interface for a component is specified in the installation descriptor
for that component.
Member Summary
Methods
ComponentLifeCycle getLifeCycle()116
org.w3c.dom.Document getServiceDescription(javax.jbi.servicedesc.ServiceEndpoint
ref)117
ServiceUnitManager getServiceUnitManager()117
boolean isExchangeWithConsumerOkay(javax.jbi.servicedesc.ServiceEndpo
int endpoint, javax.jbi.messaging.MessageExchange exchange)117
boolean isExchangeWithProviderOkay(javax.jbi.servicedesc.ServiceEndpo
int endpoint, javax.jbi.messaging.MessageExchange exchange)117
resolveEndpointReference(org.w3c.dom.DocumentFragment epr)118
javax.jbi.servicedesc.
ServiceEndpoint
Methods
getLifeCycle()
public javax.jbi.component.ComponentLifeCycle126 getLifeCycle()
Get the life cycle control interface for this component. This interface allows the JBI implementation to
control the running state of this component.
javax.jbi.component Component
getServiceDescription(ServiceEndpoint)
This method must be called before any other methods of this interface are called. In addition, the JBI
implementation must call the init() method of the component life cycle returned by this method before
calling any other methods on this interface, or the component life cycle interface.
Returns: the life cycle control interface for this component; must be non-null.
getServiceDescription(ServiceEndpoint)
public org.w3c.dom.Document
getServiceDescription(javax.jbi.servicedesc.ServiceEndpoint192 ref)
Retrieves a DOM representation containing metadata which describes the service provided by this
component, through the given endpoint. The result can use WSDL 1.1 or WSDL 2.0.
Parameters:
endpoint - the service endpoint.
Returns: the description for the specified service endpoint.
getServiceUnitManager()
public javax.jbi.component.ServiceUnitManager131 getServiceUnitManager()
Get the ServiceUnitManager for this component. If this component does not support deployments, it must
return null.
Returns: the ServiceUnitManager for this component, null if none there is none.
isExchangeWithConsumerOkay(ServiceEndpoint, MessageExchange)
public boolean isExchangeWithConsumerOkay(javax.jbi.servicedesc.ServiceEndpoint192
endpoint, javax.jbi.messaging.MessageExchange171 exchange)
This method is called by JBI to check if this component, in the role of provider of the service indicated by
the given exchange, can actually perform the operation desired.
Parameters:
endpoint - the endpoint to be used by the consumer; must be non-null.
exchange - the proposed message exchange to be performed; must be non-null.
Returns: true if this provider component can perform the the given exchange with the described
consumer.
isExchangeWithProviderOkay(ServiceEndpoint, MessageExchange)
public boolean isExchangeWithProviderOkay(javax.jbi.servicedesc.ServiceEndpoint192
endpoint, javax.jbi.messaging.MessageExchange171 exchange)
This method is called by JBI to check if this component, in the role of consumer of the service indicated by
the given exchange, can actually interact with the the provider properly. The provider is described by the
given endpoint and the service description supplied by the given endpoint.
Parameters:
endpoint - the endpoint to be used by the provider; must be non-null.
exchange - the message exchange that is to be performed.
Returns: true if this consumer component can interact with the described provider to perform the given
exchange.
resolveEndpointReference(DocumentFragment)
public javax.jbi.servicedesc.ServiceEndpoint192
resolveEndpointReference(org.w3c.dom.DocumentFragment epr)
Resolve the given endpoint reference. This is called by JBI when it is attempting to resolve the given EPR
on behalf of a component.
If this component returns a non-null result, it must conform to the following:
• This component implements the javax.jbi.servicedesc.ServiceEndpoint192 returned.
• The result must not be registered or activated with the JBI implementation.
Dynamically resolved endpoints are distinct from static ones; they must not be activated (see
ComponentContext.activateEndpoint(QName, String)120 ), nor registered (see
ComponentContext119 ) by components. They can only be used to address message exchanges; the JBI
implementation must deliver such exchanges to the component that resolved the endpoint reference (see
ComponentContext.resolveEndpointReference(DocumentFragment)125 ).
Parameters:
epr - the endpoint reference, in some XML dialect understood by the appropriate component (usually
a binding); must be non-null.
Returns: the service endpoint for the EPR; null if the EPR cannot be resolved by this component.
javax.jbi.component ComponentContext
javax.jbi.component
ComponentContext
Declaration
public interface ComponentContext
Description
This interface provides access to data needed by a JBI component about the JBI environment in which it is
installed, as well providing the means to allow the component to inform the JBI environment about services
provided by this component. This interface provides methods for the following functions:
• Get the DeliveryChannel for this component. This is required to allow the component to send and receive
message exchanges.
• Activate (and deactivate) service endpoints provided by this component.
• Register (and deregister) external endpoints provided by this component.
• Query available endpoints (internal and external).
• Query various data about the component, as installed in the JBI environment (name, workspace root, install
root, initial JNDI context, MBean Server, Transaction Manager).
• Loggers. Obtain the component’s logger and subloggers.
• MBean name creator. Access a utility for creating custom MBean names.
• EPR Resolver. Ask JBI to resolve an endpoint reference (EPR), converting it into a service endpoint.
Note: The term “NMR” (meaning Normalized Message Router) is used here to refer to the messaging system of
the JBI implementation. This term is used as a synonym for the JBI implementation, and refers only to the
logical message routing functions of a JBI implementation. It is not meant to require that JBI implementations
literally have a subsystem named “NMR”.
Member Summary
Methods
activateEndpoint(javax.xml.namespace.QName serviceName,
javax.jbi.servicedesc. java.lang.String endpointName)120
ServiceEndpoint
void deactivateEndpoint(javax.jbi.servicedesc.ServiceEndpoint
endpoint)121
void deregisterExternalEndpoint(javax.jbi.servicedesc.ServiceEndpo
int externalEndpoint)121
java.lang.String getComponentName()121
getDeliveryChannel()121
javax.jbi.messaging.De
liveryChannel
getEndpoint(javax.xml.namespace.QName service,
javax.jbi.servicedesc. java.lang.String name)122
ServiceEndpoint
org.w3c.dom.Document getEndpointDescriptor(javax.jbi.servicedesc.ServiceEndpoint
endpoint)122
ComponentContext javax.jbi.component
activateEndpoint(QName, String)
Member Summary
getEndpoints(javax.xml.namespace.QName interfaceName)122
ServiceEndpoint[]
getEndpointsForService(javax.xml.namespace.QName
javax.jbi.servicedesc. serviceName)122
ServiceEndpoint[]
getExternalEndpoints(javax.xml.namespace.QName
javax.jbi.servicedesc. interfaceName)123
ServiceEndpoint[]
getExternalEndpointsForService(javax.xml.namespace.QName
javax.jbi.servicedesc. serviceName)123
ServiceEndpoint[]
java.lang.String getInstallRoot()123
getLogger(java.lang.String suffix, java.lang.String
java.util.logging.Logg resourceBundleName)123
er
getMBeanNames()124
javax.jbi.management.M
BeanNames
getMBeanServer()124
javax.management.MBean
Server
getNamingContext()124
javax.naming.InitialCo
ntext
java.lang.Object getTransactionManager()124
java.lang.String getWorkspaceRoot()124
void registerExternalEndpoint(javax.jbi.servicedesc.ServiceEndpoin
t externalEndpoint)125
resolveEndpointReference(org.w3c.dom.DocumentFragment epr)125
ServiceEndpoint
Methods
activateEndpoint(QName, String)
activateEndpoint(javax.xml.namespace.QName serviceName,
java.lang.String endpointName)
throws JBIException
Activates the named endpoint with the NMR. Activation indicates to the NMR that this component is ready
to process requests sent to the named endpoint.
Note that the JBI implementation may call this component’s
Component.getServiceDescription(ServiceEndpoint)117 method before returning from
this method call; the component’s implementation must be ready to supply service description metadata
before the result of this activation call (a ServiceEndpoint) is known.
Parameters:
serviceName - qualified name of the service the endpoint exposes; must be non-null.
endpointName - the name of the endpoint to be activated; must be non-null and non-empty.
deactivateEndpoint(ServiceEndpoint)
Returns: a reference to the activated endpoint; must be non-null.

Throws:
javax.jbi.JBIException110 - if the endpoint cannot be activated.
deactivateEndpoint(ServiceEndpoint)
public void deactivateEndpoint(javax.jbi.servicedesc.ServiceEndpoint192 endpoint)
throws JBIException
Deactivates the given endpoint with the NMR. Deactivation indicates to the NMR that this component will
no longer process requests sent to the named endpoint.
Parameters:
endpoint - reference to the endpoint to be deactivated; must be non-null.
Throws:
javax.jbi.JBIException110 - if the endpoint cannot be deactivated.
deregisterExternalEndpoint(ServiceEndpoint)
public void deregisterExternalEndpoint(javax.jbi.servicedesc.ServiceEndpoint192
externalEndpoint)
throws JBIException
Deregisters the given external endpoint with the NMR. This indicates to the NMR that the given external
endpoint can no longer be used as a proxy for external service consumers to access an internal service of the
same service name.
Parameters:
externalEndpoint - the external endpoint to be deregistered; must be non-null.
Throws:
javax.jbi.JBIException110 - if the given external endpoint was not previously registered.
getComponentName()
public java.lang.String getComponentName()
Get the unique component name of this component, as assigned by the identification section of this
component’s installation descriptor.
Returns: the component name; must be non-null and non-empty.
getDeliveryChannel()
public javax.jbi.messaging.DeliveryChannel158 getDeliveryChannel()
throws MessagingException
Get a channel for this component to use to communicate with the Normalized Message Router. This
channel must be used by the component to send and receive message exchanges.
Returns: the delivery channel for this component; must be non-null.
Throws:
javax.jbi.messaging.MessagingException183 - if a channel has already been opened,
but not yet closed.
getEndpoint(QName, String)
getEndpoint(QName, String)
public javax.jbi.servicedesc.ServiceEndpoint192 getEndpoint(javax.xml.namespace.QName
service, java.lang.String name)
Get the service endpoint for the named activated endpoint, if any.
Parameters:
service - qualified-name of the endpoint’s service; must be non-null.
name - name of the endpoint; must be non-null.
Returns: the named endpoint, or null if the named endpoint is not activated.
getEndpointDescriptor(ServiceEndpoint)
public org.w3c.dom.Document
getEndpointDescriptor(javax.jbi.servicedesc.ServiceEndpoint192 endpoint)
throws JBIException
Retrieve the service description metadata for the specified endpoint.

Note that the result can use either the WSDL 1.1 or WSDL 2.0 description language.
Parameters:
endpoint - endpoint reference; must be non-null.
Returns: metadata describing endpoint, or null if metadata is unavailable.
Throws:
javax.jbi.JBIException110 - invalid endpoint reference.
getEndpoints(QName)
public javax.jbi.servicedesc.ServiceEndpoint[]192 getEndpoints(javax.xml.namespace.QName
interfaceName)
Queries the NMR for active endpoints that implement the given interface. This will return the endpoints for
all services and endpoints that implement the named interface (portType in WSDL 1.1). This method does
NOT include external endpoints (those registered using
registerExternalEndpoint(ServiceEndpoint)125 .
Parameters:
interfaceName - qualified name of interface/portType that is implemented by the endpoint; if
null then all activated endpoints in the JBI environment must be returned.
Returns: an array of available endpoints for the specified interface name; must be non-null; may be empty.
getEndpointsForService(QName)
public javax.jbi.servicedesc.ServiceEndpoint[]192
getEndpointsForService(javax.xml.namespace.QName serviceName)
Queries the NMR for active endpoints belonging to the given service. This method does NOT include
external endpoints (those registered using
registerExternalEndpoint(ServiceEndpoint)125 .
Parameters:
serviceName - qualified name of the service that the endpoints are part of; must be non-null.
Returns: an array of available endpoints for the specified service name; must be non-null; may be empty.
getExternalEndpoints(QName)
getExternalEndpoints(QName)
getExternalEndpoints(javax.xml.namespace.QName interfaceName)
Queries the NMR for external endpoints that implement the given interface name. This methods returns
only registered external endpoints (see registerExternalEndpoint(ServiceEndpoint)125 .
Parameters:
interfaceName - qualified name of interface implemented by the endpoints; must be non-null.
Returns: an array of available external endpoints for the specified interface name; must be non-null; may
be empty.
getExternalEndpointsForService(QName)
getExternalEndpointsForService(javax.xml.namespace.QName serviceName)
Queries the NMR for external endpoints that are part of the given service.
Parameters:
serviceName - qualified name of service that contains the endpoints; must be non-null.
Returns: an array of available external endpoints for the specified service name; must be non-null; may be
empty.
getInstallRoot()
public java.lang.String getInstallRoot()
Get the installation root directory path for this component.

This method MUST return the file path formatted for the underlying platform.
Returns: The installation root directory path, in platform-specific form; must be non-null and non-empty.
getLogger(String, String)
public java.util.logging.Logger getLogger(java.lang.String suffix,
java.lang.String resourceBundleName)
throws MissingResourceException, JBIException
Get a logger instance from JBI. Loggers supplied by JBI are guaranteed to have unique names such that
they avoid name collisions with loggers from other components created using this method. The suffix
parameter allows for the creation of subloggers as needed. The JBI specification says nothing about the
exact names to be used, only that they must be unique across components and the JBI implementation itself.
Parameters:
suffix - for creating subloggers; use an empty string for the base component logger; must be non-
null.
resourceBundleName - name of ResourceBundle to be used for localizing messages for the
logger. May be null if none of the messages require localization. The resource, if non-null, must be
loadable using the component’s class loader as the initiating loader.
Returns: a standard logger, named uniquely for this component (plus the given suffix, if applicable); must
be non-null.
getMBeanNames()
Throws:
java.util.MissingResourceException - if the ResourceBundleName is non-null and no
corresponding resource can be found.
javax.jbi.JBIException110 - if the resourceBundleName has changed from a previous
invocation by this component of this method with the same suffix.
getMBeanNames()
public javax.jbi.management.MBeanNames155 getMBeanNames()
Get a reference to the MBeanNames creator for use in creating custom MBean names.
Returns: a reference to the MBeanNames creator; must be non-null.
getMBeanServer()
public javax.management.MBeanServer getMBeanServer()
Get the JMX MBean server used to register all MBeans in the JBI environment.
Returns: a reference to the MBean server; must be non-null.
getNamingContext()
public javax.naming.InitialContext getNamingContext()
Get the JNDI naming context for this component. This context is a standard JNDI InitialContext but
its content will vary based based on the environment in which the JBI implementation is running.
Returns: the JNDI naming context; must be non-null.
getTransactionManager()
public java.lang.Object getTransactionManager()
Get the TransactionManager for this implementation. The instance returned is an implementation of the
standard JTA interface. If none is available, this method returns null.
The object returned by this method is untyped, to allow this interface to be compiled in environments that
do not support JTA. If not null, the object returned must be of type
javax.transaction.TransactionManager.
This downcast is necessary because JBI is used in environments that do not support JTA (i.e., J2SE).
Explicit use of JTA types would cause compilation failures in such environments.
Returns: A TransactionManager instance, or null if none is available in the execution environment.
getWorkspaceRoot()
public java.lang.String getWorkspaceRoot()
Get the root directory path for this component’s private workspace.
This method MUST return the file path formatted for the underlying platform.
The returned value must indicate a valid file path that the component may use to write files to, and read files
from.
Returns: The private workspace root path, in platform-specific form; must be non-null and non-empty.
registerExternalEndpoint(ServiceEndpoint)
registerExternalEndpoint(ServiceEndpoint)
public void registerExternalEndpoint(javax.jbi.servicedesc.ServiceEndpoint192
externalEndpoint)
throws JBIException
Registers the given external endpoint with the NMR. This indicates to the NMR that the given endpoint is
used as a proxy for external service consumers to access an internal service of the same service name (but a
different endpoint name).
Parameters:
externalEndpoint - the external endpoint to be registered; must be non-null.
Throws:
javax.jbi.JBIException110 - if an external endpoint with the same name is already registered,
by this or another component.
resolveEndpointReference(org.w3c.dom.DocumentFragment epr)
Resolve the given endpoint reference into a service endpoint. This is called by the component when it has
an EPR that it wants to resolve into a service endpoint.
Note that the service endpoint returned refers to a dynamic endpoint; the endpoint will exist only as long as
this component retains a strong reference to the object returned by this method. The endpoint may not be
included in the list of “activated” endpoints.
Parameters:
epr - endpoint reference as an XML fragment; must be non-null.
Returns: the service endpoint corresponding to the given endpoint reference; null if the reference cannot
be resolved.
ComponentLifeCycle javax.jbi.component
javax.jbi.component
ComponentLifeCycle
Declaration
public interface ComponentLifeCycle
Description
This interface must be implemented by a JBI component to provide initialization, start, stop, and shutdown life
cycle processing. These methods comprise the life cycle contract between the JBI implementation and the
component. The life cycle of a component begins with a call to the init() method on an instance of the
component’s implementation of this interface, and ends with the first call to the shutDown() method on that
instance. Between these two calls, there can be any number of stop() and start() calls.
The JBI implementation must track the running state of a component, and ensure that life cycle state changes
are always legal. For example, if the management interface for controlling a component’s life cycle
(javax.jbi.management.ComponentLifeCycleMBean139 ) is used to start a component that was
just installed (and thus in the Shutdown state), the implementation must invoke this component’s
init(ComponentContext)126 method before invoking its start()127 method.
Member Summary
Methods
tName
void init(ComponentContext context)126
void shutDown()127
void start()127
void stop()127
Methods
Get the JMX object name for the extension MBean for this component; if there is none, return null.
Returns: the JMX object name of the additional MBean or null if there is no additional MBean.
init(ComponentContext)
public void init(javax.jbi.component.ComponentContext119 context)
throws JBIException
Initialize the component. This performs initialization required by the component but does not make it ready
to process messages. This method is called once for each life cycle of the component.
javax.jbi.component ComponentLifeCycle
shutDown()
If the component needs to register an additional MBean to extend its life cycle, or provide other component
management tasks, it should be registered during this call.
Parameters:
context - the component’s context, providing access to component data provided by the JBI
environment; must be non-null.
Throws:
javax.jbi.JBIException110 - if the component is unable to initialize.
shutDown()
public void shutDown()
throws JBIException
Shut down the component. This performs clean-up, releasing all run-time resources used by the component.
Once this method has been called, init(ComponentContext)126 must be called before the
component can be started again with a call to start()127 .
Throws:
javax.jbi.JBIException110 - if the component is unable to shut down
start()
public void start()
throws JBIException
Start the component. This makes the component ready to process messages. This method is called after
init(ComponentContext)126 , both when the component is being started for the first time and when
the component is being restarted after a previous call to shutDown()127 . If stop()127 was called
previously but shutDown()127 was not, start() can be called again without another call to
init(ComponentContext)126 .
Throws:
javax.jbi.JBIException110 - if the component is unable to start.
stop()
public void stop()
throws JBIException
Stop the component. This makes the component stop accepting messages for processing. After a call to this
method, start()127 may be called again without first calling init(ComponentContext)126 .
Throws:
javax.jbi.JBIException110 - if the component is unable to stop
InstallationContext javax.jbi.component
getClassPathElements()
javax.jbi.component
InstallationContext
Declaration
public interface InstallationContext
Description
This context contains information necessary for a JBI component to perform its installation/uninstallation
processing. This is provided to the init() method of the component Bootstrap114 interface.
Member Summary
Methods
java.util.List getClassPathElements()128
java.lang.String getComponentClassName()128
java.lang.String getComponentName()129
ComponentContext getContext()129
getInstallationDescriptorExtension()129
org.w3c.dom.DocumentFr
agment
boolean isInstall()129
void setClassPathElements(java.util.List classPathElements)130
Methods
getClassPathElements()
public java.util.List getClassPathElements()
Get a list of elements that comprise the class path for this component. Each element represents either a
directory (containing class files) or a library file. All elements are reachable from the install root. These
elements represent class path items that the component’s execution-time component class loader uses, in
search order. All path elements must use the file separator character appropriate to the system (i.e.,
File.separator).
Returns: a list of String objects, each of which contains a class path elements. The list must contain at
least one class path element.
getComponentClassName()
public java.lang.String getComponentClassName()
Get the name of the class that implements the Component116 interface for this component. This must be
the component class name given in the component’s installation descriptor.
Returns: the Component116 implementation class name, which must be non-null and non-empty.
javax.jbi.component InstallationContext
getComponentName()
getComponentName()
public java.lang.String getComponentName()
Get the unique name assigned to this component. This name must be assigned from the component’s
installation descriptor identification section.
Returns: the unique component name, which must be non-null and non-empty.
getContext()
public javax.jbi.component.ComponentContext119 getContext()
Get the JBI context for this component. The following methods are valid to use on the context:
• ComponentContext.getMBeanNames()124
• ComponentContext.getMBeanServer()124
• ComponentContext.getNamingContext()124
• ComponentContext.getTransactionManager()124
All other methods on the returned context must throw a IllegalStateException exception if
invoked.
Returns: the JBI context for this component, which must be non-null.
getInstallationDescriptorExtension()
public org.w3c.dom.DocumentFragment getInstallationDescriptorExtension()
Return a DOM document fragment representing the installation descriptor (jbi.xml) extension data for the
component, if any.
The Installation Descriptor Extension data are located at the end of the <component> element of the
Returns: a DOM document fragment containing the installation descriptor (jbi.xml) extension data, or
null if none is present in the descriptor.
getInstallRoot()
Get the installation root directory full path name for this component. This path name must be formatted for
the platform the JBI environment is running on.
Returns: the installation root directory name, which must be non-null and non-empty.
isInstall()
public boolean isInstall()
Returns true if this context was created in order to install a component into the JBI environment. Returns
false if this context was created to uninstall a previously installed component.
This method is provided to allow Bootstrap114 implementations to tailor their behaviour according to
use case. For example, the Bootstrap.init(InstallationContext)115 method
implementation may create different types of extension MBeans, depending on the use case specified by
this method.
setClassPathElements(List)
Returns: true if this context was created in order to install a component into the JBI environment;
otherwise the context was created to uninstall an existing component.
setClassPathElements(List)
public void setClassPathElements(java.util.List classPathElements)
Set the list of elements that comprise the class path for this component. Each element represents either a
directory (containing class files) or a library file. Elements are reached from the install root. These elements
represent class path items that the component’s execution-time component class loader uses, in search
order. All file paths are relative to the install root of the component.
This method allows the component’s bootstrap to alter the execution-time class path specified by the
component’s installation descriptor. The component configuration determined during installation can affect
the class path needed by the component at execution-time. All path elements must use the file separator
character appropriate to the system (i.e., File.separator.
Parameters:
classPathElements - a list of String objects, each of which contains a class path elements; the list
must be non-null and contain at least one class path element.
Throws:
java.lang.IllegalArgumentException - if the class path elements is null, empty, or if an
individual element is ill-formed.
javax.jbi.component ServiceUnitManager
deploy(String, String)
javax.jbi.component
ServiceUnitManager
Declaration
public interface ServiceUnitManager
Description
This interface defines component-supplied methods for managing service unit deployments, and is
implemented by the component. The JBI implementation queries the component for the implementation of this
object using the Component.getServiceUnitManager()117 method.
Member Summary
Methods
java.lang.String deploy(java.lang.String serviceUnitName, java.lang.String
serviceUnitRootPath)131
void init(java.lang.String serviceUnitName, java.lang.String
void shutDown(java.lang.String serviceUnitName)132
void start(java.lang.String serviceUnitName)132
void stop(java.lang.String serviceUnitName)133
java.lang.String undeploy(java.lang.String serviceUnitName, java.lang.String
Methods
deploy(String, String)
public java.lang.String deploy(java.lang.String serviceUnitName,
java.lang.String serviceUnitRootPath)
throws DeploymentException
Deploy a Service Unit to the component. This is called by the JBI implementation in order to deploy the
given artifact to the implementing component.
Upon successful deployment, a non-empty result string must be returned, that starts with the JBI-defined
component-task-result element. For example:
<component-task-result>
<component-name>BC1</component-name>
<component-task-result-details
xmlns=“http://java.sun.com/xml/ns/jbi/management-message”>
<task-result-details>
<task-id>deploy</task-id>
<task-result>SUCCESS</task-result>
</task-result-details>
</component-task-result-details>
</component-task-result>
A failed deployment of the service unit must be reported using the component-task-result element
as well; the task-result must be set to FAILED.
ServiceUnitManager javax.jbi.component
init(String, String)
Parameters:
serviceUnitName - name of the service unit being deployed; must be non-null and non-empty and
unique among service units already deployed to the component.
serviceUnitRootPath - path of the service unit artifact root, in platform-specific format; must be
non-null and non-empty.
Returns: deployment status message, which is an XML string that conforms to the component-task-
result type from the schema given in the MBean Status and Result Strings section of the
Management chapter of the JBI specification; must be non-null and non-empty.
Throws:
javax.jbi.management.DeploymentException141 - if the deployment operation is
unsuccessful.
init(String, String)
public void init(java.lang.String serviceUnitName, java.lang.String serviceUnitRootPath)
Initialize the given deployed service unit. This is the first phase of a two-phase start, where the component
must prepare to receive service requests related to the deployment (if any).
The serviceUnitRootPath parameter is provided to facilitate restart of the component. This allows simple
components to rely entirely on JBI’s ability to persist deployment information, avoiding the need for the
component to provide its own persistence mechanism.
Parameters:
serviceUnitName - name of the service unit being initialized; must be non-null, non-empty, and
match the name of a previously deployed (but not yet undeployed) service unit.
Throws:
javax.jbi.management.DeploymentException141 - if the service unit is not deployed, or
if it is in an incorrect state.
shutDown(String)
public void shutDown(java.lang.String serviceUnitName)
Shut down the deployed service unit. This causes the component to return to the state it was in after
deploy(String, String)131 , and before init(String, String)132 .
Parameters:
serviceUnitName - name of the service unit being shut down; must be non-null, non-empty, and
Throws:
start(String)
public void start(java.lang.String serviceUnitName)
javax.jbi.component ServiceUnitManager
stop(String)
Start the deployed service unit. This is the second phase of a two-phase start, where the component can now
initiate service requests related to the deployment.
Parameters:
serviceUnitName - name of the service unit being started; must be non-null, non-empty, and
Throws:
stop(String)
public void stop(java.lang.String serviceUnitName)
Stop the deployed service unit. This causes the component to cease generating service requests related to
the given service unit. This returns the service unit to a state equivalent to after init(String,
String)132 was called.
Parameters:
serviceUnitName - name of the service unit being stopped; must be non-null, non-empty, and
Throws:
undeploy(String, String)
public java.lang.String undeploy(java.lang.String serviceUnitName,
java.lang.String serviceUnitRootPath)
Undeploy a Service Unit from the component. The service unit must be shutdown to undeploy it.
Parameters:
serviceUnitName - name of the service unit being undeployed; must be non-null, non-empty, and
Returns: deployment status message, which is an XML string that conforms to the component-task-
result type from the schema given in the MBean Status and Result Strings section of the
Management chapter of the JBI specification; must be non-null and non-empty
Throws:
javax.jbi.management.DeploymentException141 - if the undeployment operation is
unsuccessful.
CHAPTER 10
Package
javax.jbi.management
Class Summary
Interfaces
AdminServiceMBean136 This interface defines a set of administrative methods allowing a JMX-based
administrative tool to perform a variety of administrative tasks.
ComponentLifeCycleMBea ComponentLifeCycleMBean defines the standard life cycle controls for JBI Installable
n139 Components.
DeploymentServiceMBean The deployment service MBean allows administrative tools to manage service
143 assembly deployments.
InstallationServiceMBe The deployment service MBean allows administrative tools to manage service
an149 assembly deployments.
InstallerMBean151 The InstallerMBean defines standard installation and uninstallation controls for
components.
LifeCycleMBean153 LifeCycleMBean is a base interface that defines standard life cycle controls for JBI
implementation services (which are implementation-specific), and JBI components
(bindings and engines).
MBeanNames155 This interface provides methods to create JMX object names for component- supplied
MBeans.
Exceptions
DeploymentException141 DeploymentException is an exception thrown by the Deployment Service and the
Service Unit Manager.
AdminServiceMBean javax.jbi.management
AdminServiceMBean
Declaration
public interface AdminServiceMBean
Description
This interface defines a set of administrative methods allowing a JMX-based administrative tool to perform a
variety of administrative tasks.
• Find component lifecycle MBean names for:
• Individual components, by name
• All binding components
• All service engines
• Find lifecyle MBeans names for implementation-defined services:
• Individual implementation services, by name
• All implementation services
• Query whether an individual component is a binding or engine
• Query implementation information (version etc.)
Member Summary
Methods
getBindingComponents()137
tName[]
getComponentByName(java.lang.String name)137
tName
getEngineComponents()137
tName[]
java.lang.String getSystemInfo()137
getSystemService(java.lang.String serviceName)137
tName
getSystemServices()138
tName[]
boolean isBinding(java.lang.String componentName)138
boolean isEngine(java.lang.String componentName)138
javax.jbi.management AdminServiceMBean
getBindingComponents()
Methods
getBindingComponents()
public javax.management.ObjectName[] getBindingComponents()
Get a list of ComponentLifeCycleMBean139 s for all binding components currently installed in the
JBI system.
Returns: array of JMX object names of component life cycle MBeans for all installed binding
components; must be non-null; may be empty
getComponentByName(String)
public javax.management.ObjectName getComponentByName(java.lang.String name)
Find the ComponentLifeCycleMBean139 of a JBI Installable Component by its unique name.

Parameters:
name - the name of the engine or binding component; must be non- null and non-empty
Returns: the JMX object name of the component’s life cycle MBean, or null if there is no such
component with the given name
getEngineComponents()
public javax.management.ObjectName[] getEngineComponents()
Get a list of ComponentLifeCycleMBean139 s for all service engines currently installed in the JBI
system.
Returns: array of JMX object names of component life cycle MBeans for all installed service engines;
must be non-null; may be empty
getSystemInfo()
public java.lang.String getSystemInfo()
Return current version and other info about this JBI implementation. The contents of the returned string are
implementation dependent.
Returns: information string about the JBI implementation, including version information; must be non-
null and non-empty
getSystemService(String)
public javax.management.ObjectName getSystemService(java.lang.String serviceName)
Lookup a system service LifeCycleMBean153 by name. System services are implementation-defined

services which can administered through JMX, and have a life cycle.
System services are not related to service engines.
Parameters:
serviceName - name of the system service; must be non-null and non- empty; values are
implementation-dependent
Returns: JMX object name of the system service’s LifeCycleMBean, or null if there is no system
service with the given name.
getSystemServices()
getSystemServices()
public javax.management.ObjectName[] getSystemServices()
Looks up all JBI system services LifeCycleMBean153 ’s currently installed. System services are
implementation-defined services which can administered through JMX. System services are not related to
service engines.
Returns: array of LifecycleMBean JMX object names of system services currently installed in the JBI
implementation; must be non-null; may be empty
isBinding(String)
public boolean isBinding(java.lang.String componentName)
Check if a given JBI component is a Binding Component.

Parameters:
componentName - the unique name of the component; must be non-null and non-empty
Returns: true if the component is a binding component; false if the component is a service engine or
if there is no component with the given componentName installed in the JBI system
isEngine(String)
public boolean isEngine(java.lang.String componentName)
Check if a given JBI component is a Service Engine.

Parameters:
componentName - the unique name of the component; must be non-null and non-empty
Returns: true if the component is a service engine; false if the component is a binding component, or
if there is no component with the given componentName installed in the JBI system
javax.jbi.management ComponentLifeCycleMBean
ComponentLifeCycleMBean
Declaration
public interface ComponentLifeCycleMBean extends LifeCycleMBean153
All Superinterfaces: LifeCycleMBean153
Description
ComponentLifeCycleMBean defines the standard life cycle controls for JBI Installable Components.
• Initialize the component, preparing it to receive service requests.
• Start the component, allowing it to initiate service requests.
• Stop the component from initiating any more service requests.
• Shut down the component, returning it to the uninitialized state where it cannot receive service requests.
• Query the JMX object name of the extension MBean for the component.
Member Summary
Methods
tName

Fields inherited from interface LifeCycleMBean153
SHUTDOWN153, STARTED153, STOPPED153, UNKNOWN154
Methods inherited from interface LifeCycleMBean153

getCurrentState()154, shutDown()154, start()154, stop()154
Methods
throws JBIException
ComponentLifeCycleMBean javax.jbi.management
Get the JMX ObjectName for the life cycle extension MBean for this component. If there is none, return
null. Note that this MBean may serve as a container for multiple MBeans, as required by the component
implementation.
Returns: ObjectName the JMX object name of the additional MBean or null if there is no additional
MBean.
Throws:
javax.jbi.JBIException110 - if there is a failure getting component information for the
component to which this life cycle applies.
javax.jbi.management DeploymentException
DeploymentException
Declaration
public class DeploymentException extends javax.jbi.JBIException110
java.lang.Object
|
|
|
+--javax.jbi.JBIException110
|
+--javax.jbi.management.DeploymentException
Description
DeploymentException is an exception thrown by the Deployment Service and the Service Unit Manager.
Member Summary
Constructors
DeploymentException(java.lang.String message)142
DeploymentException(java.lang.String message,
java.lang.Throwable cause)142
DeploymentException(java.lang.Throwable cause)142


DeploymentException javax.jbi.management
DeploymentException(String)
Constructors
DeploymentException(String)
public DeploymentException(java.lang.String message)
Creates a new instance of DeploymentException with an exception detail message.

Parameters:
DeploymentException(String, Throwable)
public DeploymentException(java.lang.String message, java.lang.Throwable cause)
Creates a new instance of DeploymentException with the specified detail message and cause.
Parameters:
cause is not known)
DeploymentException(Throwable)
public DeploymentException(java.lang.Throwable cause)
Creates a new instance of DeploymentException with the specified cause.

Parameters:
cause is not known)
javax.jbi.management DeploymentServiceMBean
DeploymentException(Throwable)
DeploymentServiceMBean
Declaration
public interface DeploymentServiceMBean
Description
The deployment service MBean allows administrative tools to manage service assembly deployments. The
tasks supported are:
• Deploying a service assembly.
• Undeploying a previously deployed service assembly.
• Querying deployed service assemblies:
• For all components in the system.
• For a particular component.
• Control the state of deployed service assemblies:
• Start the service units that contained in the SA.
• Stop the service units that contained in the SA.
• Shut down the service units that contained in the SA.
• Query the service units deployed to a particular component.
• Check if a service unit is deployed to a particular component.
• Query the deployment descriptor for a particular service assembly.
Member Summary
Fields
static SHUTDOWN144
java.lang.String
static STARTED144
java.lang.String
static STOPPED144
java.lang.String
Methods
boolean canDeployToComponent(java.lang.String componentName)144
java.lang.String deploy(java.lang.String serviceAssemblyZipUrl)144
java.lang.String[] getComponentsForDeployedServiceAssembly(java.lang.String
serviceAssemblyName)145
java.lang.String[] getDeployedServiceAssemblies()145
java.lang.String[] getDeployedServiceAssembliesForComponent(java.lang.String
componentName)145
java.lang.String[] getDeployedServiceUnitList(java.lang.String componentName)146
java.lang.String getServiceAssemblyDescriptor(java.lang.String
serviceAssemblyName)146
DeploymentServiceMBean javax.jbi.management
SHUTDOWN
Member Summary
java.lang.String getState(java.lang.String serviceAssemblyName)146
boolean isDeployedServiceUnit(java.lang.String componentName,
java.lang.String serviceUnitName)146
java.lang.String shutDown(java.lang.String serviceAssemblyName)147
java.lang.String start(java.lang.String serviceAssemblyName)147
java.lang.String stop(java.lang.String serviceAssemblyName)147
java.lang.String undeploy(java.lang.String serviceAssemblyName)148
Fields
SHUTDOWN
public static final java.lang.String SHUTDOWN
The service assembly has been deployed, or shutdown
STARTED
public static final java.lang.String STARTED
The service assembly is started. This means that the assembly’s offered services can accept message
exchanges, and it can send exchanges to consume services.
STOPPED
public static final java.lang.String STOPPED
The service assembly is stopped. This means that the assembly’s offered services can accept message
exchanges, but it will not send any.
Methods
canDeployToComponent(String)
public boolean canDeployToComponent(java.lang.String componentName)
Returns true if the the given component accepts the deployment of service units. This is used by admin
tools to determine which components can be named in service assembly deployment descriptors.
Parameters:
componentName - name of the component; must be non-null and non-empty
Returns: true if the named component accepts deployments; false if the named component does not
accept deployments or it does not exist
deploy(String)
public java.lang.String deploy(java.lang.String serviceAssemblyZipUrl)
throws Exception
Deploys the given Service Assembly to the JBI environment.
getComponentsForDeployedServiceAssembly(String)
Note that the implementation must not automatically start the service assembly after deployment; it must
wait for the start(String)147 method to be invoked by the administrative tool.
Parameters:
serviceAssemblyZipUrl - String containing the location URL of the Service Assembly ZIP file;
must be non-null, non-empty, and a legal URL
Returns: Result/Status of the current deployment; must conform to JBI management result/status XML
schema; must be non-null and non-empty
Throws:
java.lang.Exception - if complete deployment fails
getComponentsForDeployedServiceAssembly(String)
public java.lang.String[] getComponentsForDeployedServiceAssembly(java.lang.String
serviceAssemblyName)
throws Exception
Returns an array of component names, where for each the given assembly contains a service unit for the
component.
Parameters:
serviceAssemblyName - the service assembly to be queried; must be non-null and non-empty
Returns: array of component names, where for each name the given assembly contains a service unit from
the given service assembly; must be non-null; may be empty
Throws:
java.lang.Exception - if a processing error occurs
getDeployedServiceAssemblies()
public java.lang.String[] getDeployedServiceAssemblies()
throws Exception
Returns a list of Service Assemblies deployed to the JBI environment.

Returns: list of Service Assembly names; must be non-null; may be empty
Throws:
getDeployedServiceAssembliesForComponent(String)
public java.lang.String[] getDeployedServiceAssembliesForComponent(java.lang.String
componentName)
throws Exception
Returns an array of Service Assembly names, where each assembly contains Service Units for the given
component.
Parameters:
componentName - name of the component to query; must be non-null and non-empty
Returns: array of of Service Assembly names, where each assembly contains a Service Unit for the named
component; must be non-null; may be empty
Throws:
getDeployedServiceUnitList(String)
getDeployedServiceUnitList(String)
public java.lang.String[] getDeployedServiceUnitList(java.lang.String componentName)
throws Exception
Returns an array of service unit names that are currently deployed to the named component.
Parameters:
componentName - the name of the component to query; must be non-null and non-empty
Returns: array of service unit names deployed in the named component; must be non-null; may be empty
Throws:
getServiceAssemblyDescriptor(String)
public java.lang.String getServiceAssemblyDescriptor(java.lang.String
serviceAssemblyName)
throws Exception
Returns the deployment descriptor of the Service Assembly that was deployed to the JBI enviroment,
serialized to a String.
Parameters:
serviceAssemblyName - name of the service assembly to be queried; must be non-null and non-
empty
Returns: descriptor of the Assembly Unit; must be non-null
Throws:
getState(String)
public java.lang.String getState(java.lang.String serviceAssemblyName)
throws Exception
Get the running state of a service assembly. The possible result values of this query are enumerated by the
following set of constants: SHUTDOWN144 , STOPPED144 , STARTED144 .
Parameters:
serviceAssemblyName - name of the assembly to query; must be non-null and non-empty
Returns: the state of the service assembly, as a string value; must be one of the enumerated string values
provided by this interface: SHUTDOWN144 , STOPPED144 , or STARTED144
Throws:
java.lang.Exception - if there is no such assembly
isDeployedServiceUnit(String, String)
public boolean isDeployedServiceUnit(java.lang.String componentName,
java.lang.String serviceUnitName)
throws Exception
Queries if the named Service Unit is currently deployed to the named component.
Parameters:
componentName - name of the component to query; must be non-null and non-empty
serviceUnitName - name of the subject service unit; must be non-null and non-empty
shutDown(String)
Returns: true if the named service unit is currently deployed to the named component
Throws:
java.lang.Exception
shutDown(String)
public java.lang.String shutDown(java.lang.String serviceAssemblyName)
throws Exception
Shut down the service assembly. This puts the assembly back into the SHUTDOWN144 state.
Parameters:
serviceAssemblyName - name of the assembly to be shut down; must be non-null and non-empty
Returns: result / status string giving the results of shutting down each service unit in the assembly; must
be non-null and non-empty
Throws:
java.lang.Exception - if the assembly fails to shut down
start(String)
public java.lang.String start(java.lang.String serviceAssemblyName)
throws Exception
Start the service assembly. This puts the assembly into the STARTED144 state.
Parameters:
serviceAssemblyName - name of the assembly to be started; must be non-null and non-empty
Returns: result / status string giving the results of starting (and possibly initializing) each service unit in
the assembly; must be non-null and non-empty
Throws:
java.lang.Exception - if the assembly fails to start
stop(String)
public java.lang.String stop(java.lang.String serviceAssemblyName)
throws Exception
Stop the service assembly. This puts the assembly into the STOPPED144 state.
Parameters:
serviceAssemblyName - name of the assembly to be stopped; must be non-null and non-empty
Returns: result / status string giving the results of stopping each service unit in the assembly; must be non-
null and non-empty
Throws:
java.lang.Exception - if the assembly fails to stop
undeploy(String)
undeploy(String)
public java.lang.String undeploy(java.lang.String serviceAssemblyName)
throws Exception
Undeploys the given Service Assembly from the JBI environment.

Parameters:
serviceAssemblyName - name of the Service Assembly that is to be undeployed; must be non-
null and non-empty
Returns: Result/Status of the current undeployment; must conform to JBI management result/status XML
schema; must be non-null and non-empty
Throws:
java.lang.Exception - if compelete undeployment fails
javax.jbi.management InstallationServiceMBean
installSharedLibrary(String)
InstallationServiceMBean
Declaration
public interface InstallationServiceMBean
Description
The deployment service MBean allows administrative tools to manage service assembly deployments. The
tasks supported are:
• Installing (and uninstalling) a shared library
• Creating (loading) and destroying (unloading) a component installer MBean.
• Finding an existing component installer MBean.
Installing and uninstalling components is accomplished using InstallerMBean151 s, loaded by this
MBean. An individual installer MBean is needed for each component installation / uninstalltin. This is to
support the more complex installation process that some components require.
Member Summary
Methods
java.lang.String installSharedLibrary(java.lang.String slZipURL)149
loadInstaller(java.lang.String componentName)150
tName
loadNewInstaller(java.lang.String installZipURL)150
tName
boolean uninstallSharedLibrary(java.lang.String slName)150
boolean unloadInstaller(java.lang.String componentName, boolean
isToBeDeleted)150
Methods
installSharedLibrary(String)
public java.lang.String installSharedLibrary(java.lang.String slZipURL)
Install a shared library installation package.

The return value is the unique name for the shared-library, as found in the the value of the installation
descriptor’s <identification><name> element.
Parameters:
slZipURL - URL locating a zip file containing a shared library installation package; must be non-
null, non-empty, and a legal URL
Returns: the unique name of the shared library loaded from slZipURL; must be non-null and non-empty
InstallationServiceMBean javax.jbi.management
loadInstaller(String)
loadInstaller(String)
public javax.management.ObjectName loadInstaller(java.lang.String componentName)
Load the InstallerMBean for a previously installed component.

The “component name” refers to the <identification><name> element value from the component’s
installation package (see loadNewInstaller(String)150 ).
Parameters:
componentName - the component name identifying the installer to load; must be non-null and non-
empty
Returns: the JMX ObjectName of the InstallerMBean loaded from an existing installation context; null
if the installer MBean doesn’t exist
loadNewInstaller(String)
public javax.management.ObjectName loadNewInstaller(java.lang.String installZipURL)
Load the installer for a new component for the given component installation package.
Parameters:
installZipURL - URL locating a ZIP file containing the JBI Installation package to be installed;
must be non-null, non-empty, and a legal URL
Returns: the JMX ObjectName of the InstallerMBean loaded from installZipURL; must be non-null
uninstallSharedLibrary(String)
public boolean uninstallSharedLibrary(java.lang.String slName)
Uninstall a previously installed shared library.

Parameters:
slName - the name of the shared name space to uninstall; must be non-null and non-empty
Returns: true if the uninstall was successful
unloadInstaller(String, boolean)
public boolean unloadInstaller(java.lang.String componentName, boolean isToBeDeleted)
Unload an InstallerMBean previously loaded for a component.

Parameters:
componentName - the component name identifying the installer to unload; must be non-null and
non-empty
isToBeDeleted - true if the component is to be deleted as well
Returns: true if the operation was successful, otherwise false
javax.jbi.management InstallerMBean
getInstallerConfigurationMBean()
InstallerMBean
Declaration
public interface InstallerMBean
Description
The InstallerMBean defines standard installation and uninstallation controls for components. InstallerMBeans
are created by the InstallationServiceMBean149 . The InstallerMBean offers controls to allow an
administrative tool to:
• Install the component from the installation package.
• Uninstall the component.
• Check the installation status of the component.
• Get the file path to the component’s installation root directory.
Member Summary
Methods
getInstallerConfigurationMBean()151
tName
install()152
tName
boolean isInstalled()152
void uninstall()152
Methods
getInstallerConfigurationMBean()
public javax.management.ObjectName getInstallerConfigurationMBean()
throws JBIException
Get the installer configuration MBean name for this component.

Returns: the MBean object name of the Installer Configuration MBean; null if none is provided by this
component
Throws:
javax.jbi.JBIException110 - if the component is not in the appropriate state (after install() but
before life cycle initialization), or if any error occurs during processing
getInstallRoot()
InstallerMBean javax.jbi.management
install()
Get the installation root directory path for this component.

Returns: the full installation path of this component; this must be in absolute path name form, in platform-
specific format; must be non-null and non-empty
install()
public javax.management.ObjectName install()
throws JBIException
Install a component.
Note that the implementation must leave the component in its installed, shutdown state. Automatic starting
of components during installation by implementations is not allowed.
Returns: JMX ObjectName representing the LifeCycleMBean for the installed component, or null if the
installation did not complete
Throws:
javax.jbi.JBIException110 - if the installation fails
isInstalled()
public boolean isInstalled()
Determine whether or not the component is installed.

Returns: true if this component is currently installed, otherwise false
uninstall()
public void uninstall()
throws JBIException
Uninstall the component. This completely removes the component from the JBI system.
Throws:
javax.jbi.JBIException110 - if the uninstallation fails
javax.jbi.management LifeCycleMBean
SHUTDOWN
LifeCycleMBean
Declaration
public interface LifeCycleMBean
All Known Subinterfaces: ComponentLifeCycleMBean139
Description
LifeCycleMBean is a base interface that defines standard life cycle controls for JBI implementation services
(which are implementation-specific), and JBI components (bindings and engines).
Member Summary
Fields
static SHUTDOWN153
java.lang.String
static STARTED153
java.lang.String
static STOPPED153
java.lang.String
static UNKNOWN154
java.lang.String
Methods
java.lang.String getCurrentState()154
void shutDown()154
void start()154
void stop()154
Fields
SHUTDOWN
public static final java.lang.String SHUTDOWN
Value returned by getCurrentState()154 for a shutdown component.
STARTED
public static final java.lang.String STARTED
Value returned by getCurrentState()154 for a started component.
STOPPED
public static final java.lang.String STOPPED
Value returned by getCurrentState()154 for a stopped component.
LifeCycleMBean javax.jbi.management
UNKNOWN
UNKNOWN
public static final java.lang.String UNKNOWN
Value returned by getCurrentState()154 for a component in an unknown state.
Methods
getCurrentState()
public java.lang.String getCurrentState()
Get the current state of this managed compononent.

Returns: the current state of this managed component (must be one of the string constants defined by this
interface)
shutDown()
public void shutDown()
throws JBIException
Shut down the item. This releases resources, returning the item to an uninitialized state.
Throws:
javax.jbi.JBIException110 - if the item fails to shut down
start()
public void start()
throws JBIException
Start the item.

Throws:
javax.jbi.JBIException110 - if the item fails to start
stop()
public void stop()
throws JBIException
Stop the item. This suspends current messaging activities.

Throws:
javax.jbi.JBIException110 - if the item fails to stop
javax.jbi.management MBeanNames
BOOTSTRAP_EXTENSION
MBeanNames
Declaration
public interface MBeanNames
Description
This interface provides methods to create JMX object names for component- supplied MBeans. This ensures
that component-supplied MBeans follow the JBI implementation-determined naming convention.
Components obtain instances of this name creator using
javax.jbi.component.ComponentContext.getMBeanNames()124 .
Member Summary
Fields
static BOOTSTRAP_EXTENSION155
java.lang.String
static COMPONENT_LIFE_CYCLE_EXTENSION155
java.lang.String
Methods
createCustomComponentMBeanName(java.lang.String customName)155
tName
java.lang.String getJmxDomainName()156
Fields
BOOTSTRAP_EXTENSION
public static final java.lang.String BOOTSTRAP_EXTENSION
The custom name that must be used for bootstrap extensions
COMPONENT_LIFE_CYCLE_EXTENSION
public static final java.lang.String COMPONENT_LIFE_CYCLE_EXTENSION
The custom name that must be used for component life cycle extensions
Methods
createCustomComponentMBeanName(String)
public javax.management.ObjectName createCustomComponentMBeanName(java.lang.String
customName)
Formulate and return an MBean ObjectName for a custom control of this name creator’s JBI component.
MBeanNames javax.jbi.management
getJmxDomainName()
This is used by components to create JMX names for their own JMX controls, allowing the JBI
implementation to prefix the created name to fit within the implementation’s own naming scheme.
Standard extensions must use the following custom name constants:
• Bootstrap (installer) extension: BOOTSTRAP_EXTENSION155 .
• Component life cycle extension: COMPONENT_LIFE_CYCLE_EXTENSION155 .
All other custom component MBeans must use custom names that do not collide with the standard
extension names.
Parameters:
customName - the name of the custom control; must be non-null and non-empty; must be legal for
use in a JMX object name
Returns: the JMX ObjectName of the MBean, or null if the customName is invalid
getJmxDomainName()
public java.lang.String getJmxDomainName()
Retrieve the default JMX Domain Name for MBeans registered in this instance of the JBI implementation.
Returns: the JMX domain name for this instance of the JBI implemention; must be non-null and non-
empty
CHAPTER 11
Package
javax.jbi.messaging
Class Summary
Interfaces
DeliveryChannel158 Bi-directional communication channel used by engines and bindings (hereafter called
JBI components) to interact with the Normalized Message Router.
Fault164 Marker interface for WSDL fault messages.
InOnly165 Supports operations used to process an In Only MEP to completion.
InOptionalOut167 Supports operations used to process an In Optional Out MEP to completion.
InOut169 Supports operations used to process an In Out MEP to completion.
MessageExchange171 MessageExchange represents a container for normalized messages which is described
by an exchange pattern.
MessageExchangeFactory A message exchange factory is used used to create new instances of
180 MessageExchange171 .
NormalizedMessage185 Represents a JBI Normalized Message.
RobustInOnly188 Supports operations used to process an Robust In Only MEP to completion.
Classes
ExchangeStatus162 Typesafe enumeration containing status values for a message exchange.
MessageExchange.Role179 Typesafe enumeration containing the roles a component can play in an exchange.
Exceptions
MessagingException183 Generic exception used to report messaging related errors in the Normalized Message
Router.
DeliveryChannel javax.jbi.messaging
accept()
javax.jbi.messaging
DeliveryChannel
Declaration
public interface DeliveryChannel
Description
Bi-directional communication channel used by engines and bindings (hereafter called JBI components) to
interact with the Normalized Message Router. Each JBI component has one DeliveryChannel associated
with it. Using the delivery channel, a component may:
• Receive message exchanges routed to the component (optionally, with a time-out).
• Send a message asynchronously (that is, without waiting for a response or status change acknowledging
that the exchange was received).
• Send a message synchronously, blocking the thread of execution until the result is received. Optionally, this
can be done with a time-out.
Member Summary
Methods
MessageExchange accept()158
MessageExchange accept(long timeoutMS)159
void close()159
createExchangeFactory()159
MessageExchangeFactory
createExchangeFactory(javax.xml.namespace.QName
MessageExchangeFactory interfaceName)159
createExchangeFactory(javax.jbi.servicedesc.ServiceEndpoint
MessageExchangeFactory endpoint)160
createExchangeFactoryForService(javax.xml.namespace.QName
MessageExchangeFactory serviceName)160
void send(MessageExchange exchange)160
boolean sendSync(MessageExchange exchange)160
boolean sendSync(MessageExchange exchange, long timeoutMS)161
Methods
accept()
public javax.jbi.messaging.MessageExchange171 accept()
Blocking call used to service a MessageExchange instance which has been initiated by another component.
This method supports concurrent invocation for multi-threaded environments. This must be interruptable
(Thread.interrupt()).
Returns: message exchange instance; must be non-null
javax.jbi.messaging DeliveryChannel
accept(long)
Throws:
MessagingException183 - failed to accept
MessagingException183 - when the blocked thread is interrupted
accept(long)
public javax.jbi.messaging.MessageExchange171 accept(long timeoutMS)
throws MessagingException, IllegalArgumentException
Blocking call used to service a MessageExchange instance which has been initiated by another component,
within the given timeout period. This method supports concurrent invocation for multi-threaded
environments.
Parameters:
timeoutMS - timeout period, in milliseconds (0 means no timeout); must be greater than or equal to
zero
Returns: message exchange instance, or null if timed out
Throws:
java.lang.IllegalArgumentException - if timeoutMS < 0
MessagingException183 - failed to accept
close()
public void close()
Closes the delivery channel, halting all message traffic.

Throws:
MessagingException183 - fatal error while closing channel
createExchangeFactory()
public javax.jbi.messaging.MessageExchangeFactory180 createExchangeFactory()
Create a message exchange factory. This factory will create exchange instances with all appropriate
properties set to null.
Returns: a message exchange factory; must be non-null
createExchangeFactory(QName)
public javax.jbi.messaging.MessageExchangeFactory180
createExchangeFactory(javax.xml.namespace.QName interfaceName)
Create a message exchange factory for the given interface name.

Parameters:
interfaceName - name of the interface for which all exchanges created by the returned factory will
be set for; may be null
Returns: an exchange factory that will create exchanges for the the given interface; must be non-null
createExchangeFactory(ServiceEndpoint)
createExchangeFactory(ServiceEndpoint)
createExchangeFactory(javax.jbi.servicedesc.ServiceEndpoint192 endpoint)
Create a message exchange factory for the given endpoint.

Parameters:
endpoint - endpoint for which all exchanges created by the returned factory will be set for; may be
null
Returns: an exchange factory that will create exchanges for the given endpoint; must be non-null
createExchangeFactoryForService(QName)
createExchangeFactoryForService(javax.xml.namespace.QName serviceName)
Create a message exchange factory for the given service name.

Parameters:
serviceName - name of the service for which all exchanges created by the returned factory will be
set for; may be null
Returns: an exchange factory that will create exchanges for the the given service; must be non-null
send(MessageExchange)
public void send(javax.jbi.messaging.MessageExchange171 exchange)
Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing
component. This method supports concurrent invocation for multi-threaded environments.
This is used not only to send the initial message in an exchange, but also for the servicer to “return” the
exchange with the appropriate response (response, fault, or ExchangeStatus). In more complex
message exchange patterns, a single MessageExchange can be sent back-and-forth via send() several
times, but always terminating with the MessageExchange instance being sent with a terminal
ExchangeStatus.
Parameters:
exchange - message exchange to send; must be non-null
Throws:
MessagingException183 - unable to send exchange
sendSync(MessageExchange)
public boolean sendSync(javax.jbi.messaging.MessageExchange171 exchange)
component, and blocks until the exchange is returned (that is, the other participant sends the message
exchange back). This method supports concurrent invocation for multi-threaded environments.
If the thread making this call is interrupted, the message exchange is treated in the same fashion as a timed-
out sendSync call; see sendSync(MessageExchange, long)161 .
Note that the “returned” message exchange (the instance returned by the other participant in the exchange)
is the same instance referred to by the parameter exchange.
javax.jbi.messaging DeliveryChannel
sendSync(MessageExchange, long)
Parameters:
Returns: true if the exchange has been returned (always)
Throws:
MessagingException183 - unable to send exchange, or no response is expected from the send()
operation (i.e., the MessageExchange is being used to convey an ExchangeStatus)
sendSync(MessageExchange, long)
public boolean sendSync(javax.jbi.messaging.MessageExchange171 exchange, long timeoutMS)
component, and blocks until the exchange is returned (that is, the other participant sends the message
exchange back), or the specified timeout interval elapses. This method supports concurrent invocation for
multi-threaded environments.
If the thread making this call is interrupted while this method is blocked, the message exchange is treated as
if the time out occurred.
If this method returns false (indicating that timeout occurred), the message exchange must be marked by the
implementation as being in the ExchangeStatus.ERROR163 state. Attempts by the service provider to
send a MessageExchange in such an ERROR state must result in the send (or sendSync) method called
ending abruptly with an appropriate MessagingException.
Note that the “returned” message exchange (the instance returned by the other participant in the exchange)
is the same instance referred to by the parameter exchange.
Parameters:
timeoutMS - timeout period, in milliseconds (0 means no timeout); must be greater than or equal to
zero
Returns: true if the exchange has been returned, or false if the method timed out while waiting
Throws:
java.lang.IllegalArgumentException - if timeoutMS < 0
MessagingException183 - unable to send exchange, or no response is expected from the send()
operation (i.e., the MessageExchange is being used to convey an ExchangeStatus)
ExchangeStatus javax.jbi.messaging
ACTIVE
javax.jbi.messaging
ExchangeStatus
Declaration
public final class ExchangeStatus
java.lang.Object
|
+--javax.jbi.messaging.ExchangeStatus
Description
Typesafe enumeration containing status values for a message exchange.
Member Summary
Fields
static ExchangeStatus ACTIVE162
static ExchangeStatus DONE162
static ExchangeStatus ERROR163
Methods
boolean equals(java.lang.Object obj)163
int hashCode()163
java.lang.String toString()163
static ExchangeStatus valueOf(java.lang.String status)163

clone(), finalize(), getClass(), notify(), notifyAll(), wait(long, int), wait(long,
int), wait(long, int)
Fields
ACTIVE
public static final javax.jbi.messaging.ExchangeStatus162 ACTIVE
Indicates that an ME has not been processed to completion.
DONE
public static final javax.jbi.messaging.ExchangeStatus162 DONE
Indicates that an ME has been processed to completion.
javax.jbi.messaging ExchangeStatus
ERROR
ERROR
public static final javax.jbi.messaging.ExchangeStatus162 ERROR
Indicates that an ME has terminated abnormally within the JBI environment.
Methods
equals(Object)
public boolean equals(java.lang.Object obj)
Returns true if this ExchangeStatus has the same type and value as the given object.
Overrides: equals in class Object
Parameters:
obj - value to be compared for equality
Returns: true if this object is equal to the given object in type and value
hashCode()
public int hashCode()
Returns hash code value for this object.

Overrides: hashCode in class Object
Returns: hash code value for this object
toString()
public java.lang.String toString()
Returns string value of enumerated type.

Overrides: toString in class Object
Returns: String representation of status value; must be non-null and non-empty
valueOf(String)
public static javax.jbi.messaging.ExchangeStatus162 valueOf(java.lang.String status)
Returns instance of ExchangeStatus that corresponds to given string.

Returns: ExchangeStatus corresponding to the given string value; must be non-null
Throws:
java.lang.IllegalArgumentException - if string can’t be translated (null or non-status
value)
Fault javax.jbi.messaging
valueOf(String)
javax.jbi.messaging
Fault
Declaration
public interface Fault extends NormalizedMessage185
All Superinterfaces: NormalizedMessage185
Description
Marker interface for WSDL fault messages.

Methods inherited from interface NormalizedMessage185
addAttachment(String, DataHandler)186, getAttachment(String)186,
getAttachmentNames()186, getContent()186, getProperty(String)186,
getPropertyNames()186, getSecuritySubject()187, removeAttachment(String)187,
setContent(Source)187, setProperty(String, Object)187, setSecuritySubject(Subject)187
javax.jbi.messaging InOnly
getInMessage()
javax.jbi.messaging
InOnly
Declaration
public interface InOnly extends MessageExchange171
All Superinterfaces: MessageExchange171
Description
Supports operations used to process an In Only MEP to completion.
Member Summary
Methods
NormalizedMessage getInMessage()165
void setInMessage(NormalizedMessage msg)166

Fields inherited from interface MessageExchange171
JTA_TRANSACTION_PROPERTY_NAME172
Methods inherited from interface MessageExchange171

createFault()172, createMessage()173, getEndpoint()173, getError()173,
getExchangeId()173, getFault()173, getInterfaceName()174, getMessage(String)174,
getOperation()174, getPattern()174, getProperty(String)174, getPropertyNames()175,
getRole()175, getService()175, getStatus()175, isTransacted()175,
setEndpoint(ServiceEndpoint)176, setError(Exception)176, setFault(Fault)176,
setInterfaceName(QName)176, setMessage(NormalizedMessage, String)177,
setOperation(QName)177, setProperty(String, Object)177, setService(QName)177,
setStatus(ExchangeStatus)178
Methods
getInMessage()
public javax.jbi.messaging.NormalizedMessage185 getInMessage()
Retrieves the in normalized message from this exchange.

Returns: in message; may be null
InOnly javax.jbi.messaging
setInMessage(NormalizedMessage)
public void setInMessage(javax.jbi.messaging.NormalizedMessage185 msg)
Sets the in normalized message for this exchange.

Parameters:
msg - in message; must be non-null
Throws:
MessagingException183 - unable to set in message, possibly because it has already been set
java.lang.IllegalStateException - if the component is not the owner of this message
exchange
javax.jbi.messaging InOptionalOut
getInMessage()
javax.jbi.messaging
InOptionalOut
Declaration
public interface InOptionalOut extends MessageExchange171
Description
Supports operations used to process an In Optional Out MEP to completion.
Member Summary
Methods
NormalizedMessage getOutMessage()168
void setOutMessage(NormalizedMessage msg)168


Methods
getInMessage()
Retrieves the in message reference from this exchange.

InOptionalOut javax.jbi.messaging
getOutMessage()
Throws:
exchange
getOutMessage()
public javax.jbi.messaging.NormalizedMessage185 getOutMessage()
Retrieves the out message reference from this exchange.

Returns: out message; may be null
Throws:
exchange
Specifies the in message reference for this exchange.

Parameters:
Throws:
MessagingException183 - unable to set in message
exchange
setOutMessage(NormalizedMessage)
public void setOutMessage(javax.jbi.messaging.NormalizedMessage185 msg)
Specifies the out message reference for this exchange.

Parameters:
msg - out message; must be non-null
Throws:
MessagingException183 - unable to set out message
exchange
javax.jbi.messaging InOut
getInMessage()
javax.jbi.messaging
InOut
Declaration
public interface InOut extends MessageExchange171
Description
Supports operations used to process an In Out MEP to completion.
Member Summary
Methods
NormalizedMessage getOutMessage()170
void setOutMessage(NormalizedMessage msg)170


Methods
getInMessage()
Retrieves the in message reference from this exchange.

InOut javax.jbi.messaging
getOutMessage()
Throws:
exchange
getOutMessage()
public javax.jbi.messaging.NormalizedMessage185 getOutMessage()
Retrieves the out message reference from this exchange.

Returns: out message; may be null
Throws:
exchange
Specifies the in message reference for this exchange.

Parameters:
Throws:
exchange
public void setOutMessage(javax.jbi.messaging.NormalizedMessage185 msg)
Specifies the out message reference for this exchange.

Parameters:
msg - out message; must be non-null
Throws:
exchange
javax.jbi.messaging MessageExchange
javax.jbi.messaging
MessageExchange
Declaration
public interface MessageExchange
All Known Subinterfaces: InOnly165, InOptionalOut167, InOut169, RobustInOnly188
Description
MessageExchange represents a container for normalized messages which is described by an exchange pattern.
The exchange pattern defines the names, sequence, and cardinality of messages in an exchange.
When a consumer initiates a message exchange (that is, it creates a new exchange instance and initializes it), it
has a choice of how to address the exchange, to indicate the service desired. In increasing order of specificity,
the initiating consumer may address the new exchange by:
• Service Type. The consumer supplies only the interface name, indicating the type of service desired. The
NMR chooses a suitable provider when the message is sent.
• Service Name. The consumer supplies only the service name, indicating the service provider desired, but
not the particular endpoint exposed by that provider to use. The NMR chooses a suitable endpoint when the
message is sent.
• Service Endpoint. The consumer specifies the exact service endpoint name it wishes to use. The consumer
can determine this dynamically (by querying available active endpoints), or the service endpoint can be
determined at design or deployment time. When the message exchange is sent, the NMR will attempt to
route the instance to the given endpoint only. (Note that connection metadata can alter this behaviour, by
introducing aliases for endpoints.)
The NMR will always use the most specific address type given, ignoring other, less specific ones, if any.
Note that whenever the NMR chooses the provider endpoint, it must set the endpoint property of the message
exchange instance to the endpoint it selected.
Note also that setting the different address properties of an exchange instance does not cause side effects. For
example, setting the service endpoint will not affect the previously set interface name or service name.
Member Summary
Nested Classes
static class MessageExchange.Role179
Fields
static JTA_TRANSACTION_PROPERTY_NAME172
java.lang.String
Methods
Fault createFault()172
NormalizedMessage createMessage()173
getEndpoint()173
ServiceEndpoint
java.lang.Exception getError()173
MessageExchange javax.jbi.messaging
JTA_TRANSACTION_PROPERTY_NAME
Member Summary
java.lang.String getExchangeId()173
Fault getFault()173
getInterfaceName()174
javax.xml.namespace.QN
ame
NormalizedMessage getMessage(java.lang.String name)174
getOperation()174
ame
java.net.URI getPattern()174
java.lang.Object getProperty(java.lang.String name)174
java.util.Set getPropertyNames()175
MessageExchange.Role getRole()175
getService()175
ame
ExchangeStatus getStatus()175
boolean isTransacted()175
void setEndpoint(javax.jbi.servicedesc.ServiceEndpoint endpoint)176
void setError(java.lang.Exception error)176
void setFault(Fault fault)176
void setInterfaceName(javax.xml.namespace.QName interfaceName)176
void setMessage(NormalizedMessage msg, java.lang.String name)177
void setOperation(javax.xml.namespace.QName name)177
void setProperty(java.lang.String name, java.lang.Object obj)177
void setService(javax.xml.namespace.QName service)177
void setStatus(ExchangeStatus status)178
Fields
JTA_TRANSACTION_PROPERTY_NAME
public static final java.lang.String JTA_TRANSACTION_PROPERTY_NAME
JTA transaction context property name
Methods
createFault()
public javax.jbi.messaging.Fault164 createFault()
Generic factory method for Fault objects.

Returns: a new fault message; must be non-null
Throws:
exchange
createMessage()
MessagingException183 - if the exchange is in a terminal state (getStatus()175 !=

ExchangeStatus.ACTIVE162 ), or if the message exchange pattern does not permit fault
messages
createMessage()
public javax.jbi.messaging.NormalizedMessage185 createMessage()
Creates a normalized message based on the specified message reference. The pattern governing this
exchange must contain a definition for the reference name supplied.
Returns: a new normalized message; must be non-null
Throws:
exchange
MessagingException183 - if the exchange is in a terminal state (getStatus()175 !=
ExchangeStatus.ACTIVE162 )
getEndpoint()
public javax.jbi.servicedesc.ServiceEndpoint192 getEndpoint()
Retrieves the endpoint used by this exchange.

Returns: endpoint address for this message exchange; null if not set
Throws:
exchange
getError()
public java.lang.Exception getError()
Retrieves the Exception describing the exchanges error status.

Returns: exception associated with this exchange; null if not set
Throws:
exchange
getExchangeId()
public java.lang.String getExchangeId()
Returns the unique identifier assigned by the NMR for this exchange.
Returns: unique id for this exchange; null if not set
getFault()
public javax.jbi.messaging.Fault164 getFault()
Retrieves the fault message for this exchange, if one exists. A fault/message reference is unnecessary, since
an exchange can carry at most one fault, and it is always the final message in an exchange.
Returns: fault associated with the exchange, or null if not present
getInterfaceName()
Throws:
exchange
getInterfaceName()
public javax.xml.namespace.QName getInterfaceName()
Retrieves the interface name used by this exchange.

Returns: interface name for this message exchange; null if not set
Throws:
exchange
getMessage(String)
public javax.jbi.messaging.NormalizedMessage185 getMessage(java.lang.String name)
Retrieves a normalized message based on the specified message reference.

Parameters:
name - message reference; must be non-null and non-empty
Returns: message with the specified reference name
Throws:
exchange
getOperation()
public javax.xml.namespace.QName getOperation()
Retrieves the operation used by this exchange.

Returns: operation name for this message exchange; null if not set
Throws:
exchange
getPattern()
public java.net.URI getPattern()
Returns the URI of the pattern for this exchange.

Returns: pattern URI for this exchange; null if not set
Throws:
exchange
getProperty(String)
public java.lang.Object getProperty(java.lang.String name)
Retrieves the specified property from this exchange.
getPropertyNames()
Parameters:
name - property name; must be non-null and non-empty
Returns: property value; may be null
Throws:
exchange
getPropertyNames()
public java.util.Set getPropertyNames()
Get all of the names of the properties for this exchange.

Returns: a set of all the property names, as Strings; must be non-null; may be an empty set
Throws:
exchange
getRole()
public javax.jbi.messaging.MessageExchange.Role179 getRole()
Queries the role that the caller (which must be the owner of the this exchange instance) plays in the
exchange.
Returns: Role the caller (the exchange owner) must play in the exchange; must be non-null
Throws:
exchange
getService()
public javax.xml.namespace.QName getService()
Retrieves the service used by this exchange.

Returns: service address for this message exchange; null if not set
Throws:
exchange
getStatus()
public javax.jbi.messaging.ExchangeStatus162 getStatus()
Returns the processing status of the exchange.

Returns: status of the exchange; must be non-null
isTransacted()
public boolean isTransacted()
Queries the existence of a JTA transaction context.

Returns: boolean transactional state of the exchange
setEndpoint(ServiceEndpoint)
Throws:
exchange
setEndpoint(ServiceEndpoint)
public void setEndpoint(javax.jbi.servicedesc.ServiceEndpoint192 endpoint)
Specifies the endpoint used by this exchange. Note that this must not affect the value of the Service
property of this message exchange.
Parameters:
endpoint - endpoint address; may be null
Throws:
exchange
setError(Exception)
public void setError(java.lang.Exception error)
Used to specify the source of a failure status. Invoking this method automatically adjusts the status of the
ME to ExchangeStatus.ERROR.
Parameters:
error - error cause; must be non-null
Throws:
exchange
setFault(Fault)
public void setFault(javax.jbi.messaging.Fault164 fault)
Specifies the fault message for this exchange, if one exists. A fault/message reference is unnecessary, since
an exchange can carry at most one fault, and it is always the final message in an exchange.
Parameters:
fault - fault message; may be null
Throws:
MessagingException183 - operation not permitted in the current exchange state
exchange
setInterfaceName(QName)
public void setInterfaceName(javax.xml.namespace.QName interfaceName)
Specifies the interface name used by this exchange.

Parameters:
interfaceName - interface name to be used by this exchange; may be null
setMessage(NormalizedMessage, String)
Throws:
exchange
setMessage(NormalizedMessage, String)
public void setMessage(javax.jbi.messaging.NormalizedMessage185 msg,
java.lang.String name)
Sets a normalized message with the specified message reference. The pattern governing this exchange must
contain a definition for the reference name supplied.
Parameters:
msg - normalized message; must be non-null
name - message reference; must be non-null and non-empty
Throws:
MessagingException183 - operation not permitted in the current exchange state
exchange
setOperation(QName)
public void setOperation(javax.xml.namespace.QName name)
Specifies the operation used by this exchange.

Parameters:
name - operation name; may be null
Throws:
exchange
setProperty(String, Object)
public void setProperty(java.lang.String name, java.lang.Object obj)
Specifies a property for this exchange.

Parameters:
obj - property value; may be null
Throws:
exchange
setService(QName)
public void setService(javax.xml.namespace.QName service)
Specifies the service used by this exchange.

Parameters:
service - service address; may be null
setStatus(ExchangeStatus)
Throws:
exchange
setStatus(ExchangeStatus)
public void setStatus(javax.jbi.messaging.ExchangeStatus162 status)
Sets the processing status of the exchange.

Parameters:
status - exchange status; must be non-null
Throws:
MessagingException183 - failed to set status, possibly due to an invalid state transition.
exchange
javax.jbi.messaging MessageExchange.Role
CONSUMER
javax.jbi.messaging
MessageExchange.Role
Declaration
public static final class MessageExchange.Role
java.lang.Object
|
+--javax.jbi.messaging.MessageExchange.Role
Enclosing Class: MessageExchange171
Description
Typesafe enumeration containing the roles a component can play in an exchange.
Member Summary
Fields
static CONSUMER179
static PROVIDER179

toString(), wait(long, int), wait(long, int), wait(long, int)
Fields
CONSUMER
public static final javax.jbi.messaging.MessageExchange.Role179 CONSUMER
Component is the service consumer.
PROVIDER
public static final javax.jbi.messaging.MessageExchange.Role179 PROVIDER
Component is the service provider.
MessageExchangeFactory javax.jbi.messaging
createExchange(QName, QName)
javax.jbi.messaging
Declaration
public interface MessageExchangeFactory
Description
A message exchange factory is used used to create new instances of MessageExchange171 . Service
consumers use these factories to create message exchanges when initiating a new service request.
Message exchange factories are created using the javax.jbi.component.ComponentContext119
given to the component during its initialization (see
javax.jbi.component.ComponentLifeCycle126 ). There are a variety of ways to creating such
factories, each of which creates a context that is used to provide some of the default properties of
MessageExchange171 instances created by the factory instances. For example, a factory can be created for
a particular endpoint, ensuring that all exchanges created by the factory have that endpoint set as the default
endpoint property of the exchange. This allows components to retain factories as a way of aligning internal
processing context with the context contained in the factory, ensuring that the exchanges created consistently
reflect that context.
Member Summary
Methods
MessageExchange createExchange(javax.xml.namespace.QName serviceName,
javax.xml.namespace.QName operationName)180
MessageExchange createExchange(java.net.URI pattern)181
InOnly createInOnlyExchange()181
InOptionalOut createInOptionalOutExchange()181
InOut createInOutExchange()181
RobustInOnly createRobustInOnlyExchange()182
Methods
createExchange(QName, QName)
public javax.jbi.messaging.MessageExchange171 createExchange(javax.xml.namespace.QName
serviceName, javax.xml.namespace.QName operationName)
Creates a new MessageExchange instance used to initiate a service invocation.

JBI defines a set of four basic message exchange types, corresponding to the predefined in-* WSDL 2.0
Message Exchange Patterns. Message exchanges of any type are created using the DeliveryChannel.
Parameters:
serviceName - the name of the service to be invoked; must be non-null
operationName - the name of the operation to be invoked; must be non-null and non-empty
javax.jbi.messaging MessageExchangeFactory
createExchange(URI)
Returns: new message exchange, initialized for invoking the given service and operation; must be non-
null
Throws:
MessagingException183 - if the given service or operation are not registered with the NMR.
MessagingException183 - if the factory was created for a particular interface, and the given
serviceName does not implement that interface.
createExchange(URI)
public javax.jbi.messaging.MessageExchange171 createExchange(java.net.URI pattern)
Creates a new MessageExchange instance used to initiate a service invocation. JBI defines a set of four
fundamental message exchange types which are created using binding and engine delivery channels. This
base method is provided for extensibility, to satisfy the need for vendor-specific message exchange
patterns. The registration and administration of these patterns is not addressed by JBI.
Parameters:
pattern - message exchange pattern; must be non-null and non-empty
Returns: new message exchange; must be non-null
Throws:
MessagingException183 - specified pattern is not registered to a message exchange type
createInOnlyExchange()
public javax.jbi.messaging.InOnly165 createInOnlyExchange()
Convenience method that creates an In-Only message exchange.

Returns: new InOnly message exchange; must be non-null
Throws:
MessagingException183 - failed to create exchange
createInOptionalOutExchange()
public javax.jbi.messaging.InOptionalOut167 createInOptionalOutExchange()
Convenience method that creates an In-Optional-Out message exchange.

Returns: new InOptionalOut message exchange; must be non-null
Throws:
createInOutExchange()
public javax.jbi.messaging.InOut169 createInOutExchange()
Convenience method that creates an In Out message exchange.

Returns: new InOut message exchange; must be non-null
createRobustInOnlyExchange()
Throws:
public javax.jbi.messaging.RobustInOnly188 createRobustInOnlyExchange()
Convenience method that creates a Robust-In-Only message exchange.

Returns: new RobustInOnly message exchange; must be non-null
Throws:
javax.jbi.messaging MessagingException
javax.jbi.messaging
MessagingException
Declaration
public class MessagingException extends javax.jbi.JBIException110
java.lang.Object
|
|
|
+--javax.jbi.JBIException110
|
+--javax.jbi.messaging.MessagingException
Description
Generic exception used to report messaging related errors in the Normalized Message Router.
Member Summary
Constructors
MessagingException(java.lang.String msg)184
MessagingException(java.lang.String msg, java.lang.Throwable
cause)184
MessagingException(java.lang.Throwable cause)184


MessagingException javax.jbi.messaging
MessagingException(String)
Constructors
MessagingException(String)
public MessagingException(java.lang.String msg)
Create a new MessagingException.

Parameters:
msg - error detail; must be non-null
MessagingException(String, Throwable)
public MessagingException(java.lang.String msg, java.lang.Throwable cause)
Create a new MessagingException with the specified cause and error text.
Parameters:
msg - error detail; must be non-null
cause - underlying error; may be null
MessagingException(Throwable)
public MessagingException(java.lang.Throwable cause)
Create a new MessagingException with the specified cause.

Parameters:
cause - underlying error; may be null
javax.jbi.messaging NormalizedMessage
MessagingException(Throwable)
javax.jbi.messaging
NormalizedMessage
Declaration
public interface NormalizedMessage
All Known Subinterfaces: Fault164
Description
Represents a JBI Normalized Message. A normalized message consists of:
• Content. The XML “payload” message, which conforms to the abstract WSDL message given in the
service description. (WSDL 1.1-described messages are converted to a JBI-defined XML “wrapper”
format.)
• Attachments. Extra (generally binary) attachments to the main message.
• Security subject. The security subject associated with the content.
• Properties. Other message-related data other than the first-class items listed above. Properties are name/
value pairs. There are some JBI-defined names (and corresponding value types). This may be extended by
components to include component-specific properties.
Member Summary
Methods
void addAttachment(java.lang.String id,
javax.activation.DataHandler content)186
getAttachment(java.lang.String id)186
javax.activation.DataH
andler
java.util.Set getAttachmentNames()186
getContent()186
javax.xml.transform.So
urce
java.lang.Object getProperty(java.lang.String name)186
java.util.Set getPropertyNames()186
getSecuritySubject()187
javax.security.auth.Su
bject
void removeAttachment(java.lang.String id)187
void setContent(javax.xml.transform.Source content)187
void setProperty(java.lang.String name, java.lang.Object value)187
void setSecuritySubject(javax.security.auth.Subject subject)187
NormalizedMessage javax.jbi.messaging
addAttachment(String, DataHandler)
Methods
addAttachment(String, DataHandler)
public void addAttachment(java.lang.String id, javax.activation.DataHandler content)
Add an attachment to this message.

Parameters:
id - unique identifier for the attachment; must be non-null and non-empty
content - attachment content; must be non-null
Throws:
MessagingException183 - failed to add attachment
getAttachment(String)
public javax.activation.DataHandler getAttachment(java.lang.String id)
Retrieve an attachment to this message with the specified identifier.

Parameters:
id - unique identifier for attachment; must be non-null and non-empty
Returns: DataHandler representing attachment content, or null if an attachment with the specified
identifier is not found
getAttachmentNames()
public java.util.Set getAttachmentNames()
Returns a list of identifiers for all attachments to this message.

Returns: a Set of attachment identifier Strings; must be non-null; may be empty
getContent()
public javax.xml.transform.Source getContent()
Retrieve the content of this message.

Returns: message content; may be null
getProperty(String)
public java.lang.Object getProperty(java.lang.String name)
Retrieve a property from the message.

Parameters:
Returns: property value, or null if the property does not exist or has no value
getPropertyNames()
public java.util.Set getPropertyNames()
Retrieve a set of property names for this message.
javax.jbi.messaging NormalizedMessage
getSecuritySubject()
Returns: set of property names for this message; must be non-null; may be empty
getSecuritySubject()
public javax.security.auth.Subject getSecuritySubject()
Get the security subject associated with this message.

Returns: the security subject associated with this message; null if none.
removeAttachment(String)
public void removeAttachment(java.lang.String id)
Removes the attachment from this message with the specified unique identifier.
Parameters:
id - attachment identifier; must be non-null and non-empty
Throws:
MessagingException183 - failed to remove attachment or the attachment does not exist
setContent(Source)
public void setContent(javax.xml.transform.Source content)
Set the content of this message.

Parameters:
content - message content; may be null
Throws:
MessagingException183 - failed to set content
setProperty(String, Object)
public void setProperty(java.lang.String name, java.lang.Object value)
Set a property on the message.

Parameters:
value - property value; may be null
setSecuritySubject(Subject)
public void setSecuritySubject(javax.security.auth.Subject subject)
Set the security subject associated with this message.

Parameters:
subject - the security subject to associate with this message; may be null
RobustInOnly javax.jbi.messaging
getInMessage()
javax.jbi.messaging
RobustInOnly
Declaration
public interface RobustInOnly extends MessageExchange171
Description
Supports operations used to process an Robust In Only MEP to completion.
Member Summary
Methods


Methods
getInMessage()
Retrieves the in normalized message from this exchange.

javax.jbi.messaging RobustInOnly
Throws:
exchange
Sets the in normalized message for this exchange.

Parameters:
Throws:
exchange
CHAPTER 12
Package
javax.jbi.servicedesc
Class Summary
Interfaces
ServiceEndpoint192 Reference to an endpoint, used to refer an endpoint as well as query information about
the endpoint.
ServiceEndpoint javax.jbi.servicedesc
getAsReference(QName)
javax.jbi.servicedesc
ServiceEndpoint
Declaration
public interface ServiceEndpoint
Description
Reference to an endpoint, used to refer an endpoint as well as query information about the endpoint.
An endpoint is an addressable entity in the JBI system, used for accessing the provider of a specific service.
This interface is implemented by both the JBI implementation and JBI components, in the following use cases:
• Activated endpoints: created by JBI implementation.
• Internal endpoints from endpoint resolution: created by the component implementation.
• Registered external endpoints: created by the component implementation.
See the JBI Specification for details on requirements imposed on components in the latter two use cases.
Member Summary
Methods
getAsReference(javax.xml.namespace.QName operationName)192
org.w3c.dom.DocumentFr
agment
java.lang.String getEndpointName()193
getInterfaces()193
ame[]
getServiceName()193
ame
Methods
getAsReference(QName)
public org.w3c.dom.DocumentFragment getAsReference(javax.xml.namespace.QName
operationName)
Get a reference to this endpoint, using an endpoint reference vocabulary that is known to the provider.
Parameters:
operationName - the name of the operation to be performed by a consumer of the generated EPR;
null if this is not applicable
Returns: endpoint reference as an XML fragment; null if the provider does not support such references
javax.jbi.servicedesc ServiceEndpoint
getEndpointName()
getEndpointName()
public java.lang.String getEndpointName()
Returns the endpoint name of this reference.

Returns: endpoint name; must be non-null and non-empty
getInterfaces()
public javax.xml.namespace.QName[] getInterfaces()
Get the qualified names of all the interfaces implemented by this service endpoint.
Returns: array of all interfaces implemented by this service endpoint; must be non-null and non-empty
getServiceName()
public javax.xml.namespace.QName getServiceName()
Returns the service name of this reference.

Returns: qualified service name; must be non-null
getServiceName()
ALMANAC LEGEND
The almanac presents classes and intefaces in alphabetic order, regardless of their package. Fields, methods and
constructors are in alphabetic order in a single list.
This almanac is modeled after the style introduced by Patrick Chan in his excellent book Java Developers
Almanac.
➊➘ ➋➘
RealtimeThread javax.realtime
➌➙ Object
➥ Thread ➍➙ Runnable
➥ RealtimeThread Schedulable
void addToFeasibility()
➎➘ ➏➘ RealtimeThread currentRealtimeThread()
1.3 ❏ Scheduler getScheduler()
❉ RealtimeThread()
1.3 ❉ RealtimeThread(SchedulingParameters scheduling)
❏ void sleep(Clock clock, HighResolutionTime time)
➚ ➚ throws InterruptedException
➐ ➑
1. Name of the class, interface, nested class or nested interface. Interfaces are italic.
2. Name of the package containing the class or interface.
3. Inheritance hierarchy. In this example, RealtimeThread extends Thread, which extends Object.
4. Implemented interfaces. The interface is to the right of, and on the same line as, the class that implements
it. In this example, Thread implements Runnable, and RealtimeThread implements
Schedulable.
5. The first column above is for the value of the @since comment, which indicates the version in which the
item was introduced.
6. The second column above is for the following icons. If the “protected” symbol does not appear, the
member is public. (Private and package-private modifiers also have no symbols.) One symbol from each
group can appear in this column.
Modifiers Access Modifiers Constructors and Fields
❍ abstract ♦protected ❉ constructor
● final ✍ field
❏ static
■ static final
7. Return type of a method or declared type of a field. Blank for constructors.

8. Name of the constructor, field or method. Nested classes are listed in 1, not here.
CHAPTER 13
Almanac
AdminServiceMBean
javax.management.ObjectName[] getBindingComponents()
javax.management.ObjectName getComponentByName(String name)
javax.management.ObjectName[] getEngineComponents()
String getSystemInfo()
javax.management.ObjectName getSystemService(String serviceName)
javax.management.ObjectName[] getSystemServices()
boolean isBinding(String componentName)
boolean isEngine(String componentName)
Bootstrap javax.jbi.component
Bootstrap
void cleanUp() throws javax.jbi.JBIException
javax.management.ObjectName getExtensionMBeanName()
void init(InstallationContext installContext) throws javax.jbi.JBIException
void onInstall() throws javax.jbi.JBIException
void onUninstall() throws javax.jbi.JBIException
Component
ComponentLifeCycle getLifeCycle()
org.w3c.dom.Document getServiceDescription(javax.jbi.servicedesc.ServiceEndpoint ref)
ServiceUnitManager getServiceUnitManager()
boolean isExchangeWithConsumerOkay(javax.jbi.servicedesc.ServiceEndpoint en
dpoint, javax.jbi.messaging.MessageExchange exchange)
boolean isExchangeWithProviderOkay(javax.jbi.servicedesc.ServiceEndpoint end
point, javax.jbi.messaging.MessageExchange exchange)
javax.jbi.servicedesc.ServiceEndp resolveEndpointReference(org.w3c.dom.DocumentFragment epr)
oint
Almanac
ComponentContext
javax.jbi.servicedesc.ServiceEndp activateEndpoint(javax.xml.namespace.QName serviceName,
oint String endpointName) throws javax.jbi.JBIException
void deactivateEndpoint(javax.jbi.servicedesc.ServiceEndpoint endpoint)
throws javax.jbi.JBIException
void deregisterExternalEndpoint(javax.jbi.servicedesc.ServiceEndpoint extern
alEndpoint) throws javax.jbi.JBIException
String getComponentName()
javax.jbi.messaging.DeliveryChan getDeliveryChannel() throws javax.jbi.messaging.MessagingException
nel
javax.jbi.servicedesc.ServiceEndp getEndpoint(javax.xml.namespace.QName service, String name)
oint
org.w3c.dom.Document getEndpointDescriptor(javax.jbi.servicedesc.ServiceEndpoint endpoint)
throws javax.jbi.JBIException
javax.jbi.servicedesc.ServiceEndp getEndpoints(javax.xml.namespace.QName interfaceName)
oint[]
javax.jbi.servicedesc.ServiceEndp getEndpointsForService(javax.xml.namespace.QName serviceName)
oint[]
javax.jbi.servicedesc.ServiceEndp getExternalEndpoints(javax.xml.namespace.QName interfaceName)
oint[]
javax.jbi.servicedesc.ServiceEndp getExternalEndpointsForService(javax.xml.namespace.QName serviceNa
oint[] me)
String getInstallRoot()
java.util.logging.Logger getLogger(String suffix, String resourceBundleName)
throws java.util.MissingResourceException, javax.jbi.JBIException
javax.jbi.management.MBeanNam getMBeanNames()
es
javax.management.MBeanServer getMBeanServer()
javax.naming.InitialContext getNamingContext()
Object getTransactionManager()
String getWorkspaceRoot()
void registerExternalEndpoint(javax.jbi.servicedesc.ServiceEndpoint externalE
ndpoint) throws javax.jbi.JBIException
javax.jbi.servicedesc.ServiceEndp resolveEndpointReference(org.w3c.dom.DocumentFragment epr)
oint
ComponentLifeCycle javax.jbi.component
ComponentLifeCycle
javax.management.ObjectName getExtensionMBeanName()
void init(ComponentContext context) throws javax.jbi.JBIException
void shutDown() throws javax.jbi.JBIException
void start() throws javax.jbi.JBIException
void stop() throws javax.jbi.JBIException
ComponentLifeCycleMBean javax.jbi.management
ComponentLifeCycleMBean LifeCycleMBean
javax.management.ObjectName getExtensionMBeanName() throws javax.jbi.JBIException
Almanac
DeliveryChannel
MessageExchange accept() throws MessagingException
MessageExchange accept(long timeoutMS) throws MessagingException,
IllegalArgumentException
void close() throws MessagingException
MessageExchangeFactory createExchangeFactory()
MessageExchangeFactory createExchangeFactory(javax.xml.namespace.QName interfaceName)
MessageExchangeFactory createExchangeFactory(javax.jbi.servicedesc.ServiceEndpoint endpoint)
MessageExchangeFactory createExchangeFactoryForService(javax.xml.namespace.QName service
Name)
void send(MessageExchange exchange) throws MessagingException
boolean sendSync(MessageExchange exchange) throws MessagingException
boolean sendSync(MessageExchange exchange, long timeoutMS)
DeploymentException javax.jbi.management
Object
➥Throwable java.io.Serializable
➥Exception
➥javax.jbi.JBIException
➥DeploymentException
❉ DeploymentException(String message)
❉ DeploymentException(String message, Throwable cause)
❉ DeploymentException(Throwable cause)
DeploymentServiceMBean
boolean canDeployToComponent(String componentName)
String deploy(String serviceAssemblyZipUrl) throws Exception
String[] getComponentsForDeployedServiceAssembly(String serviceAssemblyNa
me) throws Exception
String[] getDeployedServiceAssemblies() throws Exception
String[] getDeployedServiceAssembliesForComponent(String componentName)
throws Exception
String[] getDeployedServiceUnitList(String componentName) throws Exception
String getServiceAssemblyDescriptor(String serviceAssemblyName)
throws Exception
String getState(String serviceAssemblyName) throws Exception
boolean isDeployedServiceUnit(String componentName, String serviceUnitName)
throws Exception
✍■ String SHUTDOWN
String shutDown(String serviceAssemblyName) throws Exception
String start(String serviceAssemblyName) throws Exception
✍■ String STARTED
Almanac
String stop(String serviceAssemblyName) throws Exception

✍■ String STOPPED
String undeploy(String serviceAssemblyName) throws Exception
ExchangeStatus javax.jbi.messaging
Object
➥ExchangeStatus
✍■ ExchangeStatus ACTIVE
✍■ ExchangeStatus DONE
boolean equals(Object obj)
✍■ ExchangeStatus ERROR
int hashCode()
String toString()
❏ ExchangeStatus valueOf(String status)
Fault javax.jbi.messaging
Fault NormalizedMessage
InOnly javax.jbi.messaging
InOnly MessageExchange
NormalizedMessage getInMessage()
void setInMessage(NormalizedMessage msg) throws MessagingException
InOptionalOut javax.jbi.messaging
InOptionalOut MessageExchange
NormalizedMessage getOutMessage()
void setOutMessage(NormalizedMessage msg) throws MessagingException
InOut javax.jbi.messaging
InOut MessageExchange
NormalizedMessage getOutMessage()
void setOutMessage(NormalizedMessage msg) throws MessagingException
InstallationContext
java.util.List getClassPathElements()
String getComponentClassName()
String getComponentName()
ComponentContext getContext()
org.w3c.dom.DocumentFragment getInstallationDescriptorExtension()
Almanac
boolean isInstall()
void setClassPathElements(java.util.List classPathElements)
InstallationServiceMBean javax.jbi.management
InstallationServiceMBean
String installSharedLibrary(String slZipURL)
javax.management.ObjectName loadInstaller(String componentName)
javax.management.ObjectName loadNewInstaller(String installZipURL)
boolean uninstallSharedLibrary(String slName)
boolean unloadInstaller(String componentName, boolean isToBeDeleted)
InstallerMBean javax.jbi.management
InstallerMBean
javax.management.ObjectName getInstallerConfigurationMBean() throws javax.jbi.JBIException
javax.management.ObjectName install() throws javax.jbi.JBIException
boolean isInstalled()
void uninstall() throws javax.jbi.JBIException
Object
➥Exception
➥JBIException
❉ JBIException(String message)
❉ JBIException(String message, Throwable cause)
❉ JBIException(Throwable cause)
LifeCycleMBean javax.jbi.management
LifeCycleMBean
String getCurrentState()
✍■ String SHUTDOWN
void shutDown() throws javax.jbi.JBIException
void start() throws javax.jbi.JBIException
✍■ String STARTED
void stop() throws javax.jbi.JBIException
✍■ String STOPPED
✍■ String UNKNOWN
Almanac
MBeanNames javax.jbi.management
MBeanNames
✍■ String BOOTSTRAP_EXTENSION
✍■ String COMPONENT_LIFE_CYCLE_EXTENSION
javax.management.ObjectName createCustomComponentMBeanName(String customName)
String getJmxDomainName()
MessageExchange
Fault createFault() throws MessagingException
NormalizedMessage createMessage() throws MessagingException
javax.jbi.servicedesc.ServiceEndp getEndpoint()
oint
Exception getError()
String getExchangeId()
Fault getFault()
javax.xml.namespace.QName getInterfaceName()
NormalizedMessage getMessage(String name)
javax.xml.namespace.QName getOperation()
java.net.URI getPattern()
Object getProperty(String name)
java.util.Set getPropertyNames()
MessageExchange.Role getRole()
javax.xml.namespace.QName getService()
ExchangeStatus getStatus()
boolean isTransacted()
✍■ String JTA_TRANSACTION_PROPERTY_NAME
void setEndpoint(javax.jbi.servicedesc.ServiceEndpoint endpoint)
void setError(Exception error)
void setFault(Fault fault) throws MessagingException
void setInterfaceName(javax.xml.namespace.QName interfaceName)
void setMessage(NormalizedMessage msg, String name)
void setOperation(javax.xml.namespace.QName name)
void setProperty(String name, Object obj)
void setService(javax.xml.namespace.QName service)
void setStatus(ExchangeStatus status) throws MessagingException
MessageExchange.Role javax.jbi.messaging
Object
➥MessageExchange.Role
✍■ MessageExchange.Role CONSUMER
✍■ MessageExchange.Role PROVIDER
Almanac
MessageExchange createExchange(javax.xml.namespace.QName serviceName,
javax.xml.namespace.QName operationName)
MessageExchange createExchange(java.net.URI pattern) throws MessagingException
InOnly createInOnlyExchange() throws MessagingException
InOptionalOut createInOptionalOutExchange() throws MessagingException
InOut createInOutExchange() throws MessagingException
RobustInOnly createRobustInOnlyExchange() throws MessagingException
MessagingException javax.jbi.messaging
Object
➥Exception
➥javax.jbi.JBIException
➥MessagingException
❉ MessagingException(String msg)
❉ MessagingException(String msg, Throwable cause)
❉ MessagingException(Throwable cause)
NormalizedMessage javax.jbi.messaging
NormalizedMessage
void addAttachment(String id, javax.activation.DataHandler content)
javax.activation.DataHandler getAttachment(String id)
java.util.Set getAttachmentNames()
javax.xml.transform.Source getContent()
Object getProperty(String name)
java.util.Set getPropertyNames()
javax.security.auth.Subject getSecuritySubject()
void removeAttachment(String id) throws MessagingException
void setContent(javax.xml.transform.Source content)
void setProperty(String name, Object value)
void setSecuritySubject(javax.security.auth.Subject subject)
RobustInOnly MessageExchange
Almanac
ServiceEndpoint
org.w3c.dom.DocumentFragment getAsReference(javax.xml.namespace.QName operationName)
String getEndpointName()
javax.xml.namespace.QName[] getInterfaces()
javax.xml.namespace.QName getServiceName()
ServiceUnitManager
String deploy(String serviceUnitName, String serviceUnitRootPath)
throws javax.jbi.management.DeploymentException
void init(String serviceUnitName, String serviceUnitRootPath)
void shutDown(String serviceUnitName)
void start(String serviceUnitName)
void stop(String serviceUnitName)
String undeploy(String serviceUnitName, String serviceUnitRootPath)
CHAPTER 14
Future Directions
Like any 1.0 version of a specification, JBI 1.0 is the start of what in the future will be a more elaborate, and
complete specification. This section summarizes what directions are anticipated in future versions of JBI. This
chapter is provided for informational purposes; it is non-normative. This may include the following:
• J2ME requirements: possibly running JBI (or a subset of it) on J2ME.
• Futher support for customized message exchange patterns.
• Adoption of a work manager (from another JSR) to allow components to not have to manage their own
threads.
• Long-lived MessageExchanges. Currently message exchange instances are considered to be short-lived, so

there are no architected features for controlling resources consumed by them (e.g., “dehydration” of
normalized messages to reduce memory footprint).
• Persistence of MessageExchanges. Currently message exchanges are not serializable; they cannot be
persisted for purposes of failure recovery.
• Distributed JBI. JBI, as currently defined, is not distributed. Distributed implementations may require
support in the JBI specification to address issues that arise only in distributed systems.
• Handlers. It has been proposed that JBI define a standard type of message exchange handler, that can be
installed (in chains) in delivery channels. This would allow composition of interesting functions that can
added to components unobtrusively.
• Policy - framework, language (JSR 265). JBI 1.0 specifies a simple mechanism for expressing capabilities
(required and provided), and has three “hooks” for allowing components and the JBI implementation to
apply policies during these capabilities as inputs. Efforts such as JSR 265 will define standard access to
policy engines, policy language abstracts, etc. that may allow improvements on the JBI 1.0 mechanisms, or
Future Directions
require JBI to specify mappings to and from standardized expressions of capabilities.
• Security - SAML, other JSRs, interprocess protections, JMX security. JBI 1.0 provides a basic mechanism
for carrying security subject information with normalized messages, leaving other security aspects
(authentication of those subjects, and authorization) up to components (and JBI implementations) to
provide. It has been proposed that JBI implementations could provide some help with these remaining
aspects of security, perhaps leveraging services description metadata.
• Allow shared libraries to be used by Bootstrap implementations.
As the Java community gains experience with using JBI, other ideas for improving and extending JBI 1.0 will
arise. Since JBI touches three distinct developer communities (for JBI implementations, components, and
“applications”), the ideas may be unusually diverse. In addition, JBI is strongly aligned with web services
messaging models, which are still being actively developed and improved on by the standards community. This
alignment could be a further source of changes to improve and extend future versions of JBI.
CHAPTER 15
Appendix: Use of Transactions
This appendix contains information on how transactions can be used by JBI components to accomplish two
common goals:
• Control the reliability of internal message exchanges
• Handle external transaction protocols
The contents of this appendix are largely not normative; they are meant to illustrate some intented uses of
transactions by JBI components to achieve certain qualities of service.
15.1 Quality of Service
15.1.1 Reliability
JBI is a solution in the enterprise computing arena, thus it requires a high-level of reliability. From the NMR
point of view, this means that the message delivery design needs to address features that allow for at least a
minimum level message exchange reliability. The NMR API's don't need to enforce 100% reliability, they just
need to make that level of service available when needed. Allowing a range of reliability enables a range of
solutions for BC and SE implementers.
15.1.2 Transactional
Transactions have wide applicability in JBI-based applications. Using JBI to compose services will often
require the sharing of a transaction context between JBI engines/bindings. Such transactions can facilitate
reliable operation of composed services. The NMR facilitates the composition of business processing and
communication, including sharing of transaction contexts.
The NMR MAY include transactional pieces itself.
The unit of work in the NMR is a Message Exchange. This is also the unit of work when a transaction is being
used. The NMR is considered to be transaction aware. If the NMR is told that the Message Exchange is being
controlled by a transaction, the NMR will internally use the transaction, if required, and will pass the transaction
context along with the Message Exchange.
The primary reason for the inclusion of transactions is to assist in the primary responsibility of reliable
messaging. Without transactions the One-Way communications primitive could not be used in a reliable
fashion. The extension of transactions to other communications primitives is for completeness.
It should also be noted that the preceding assumes single JVM/JBI transactions. This is not meant to preclude
the use of distributed transactions, but the standards for such transactions are not yet mature enough to be
incorporated by JBI directly. Future versions of JBI may address distributed transactions directly.
15.1.3 Persistence
Persistence is the ability to persist the state of a Message Exchange at defined point during the Message
Exchange lifetime. Persistence is a step below the Transactional. Persistence doesn't allow the coordination of
multiple components. It does allow the Message Exchange state to be saved, typically to bound the work
required during restart recovery (i.e. a transformation engine may wish to save the results of the XSLT
transformation so that it this won't have to be redone given the relative expense of the transformation versus
persisting the result.)
The general support for persistence is tied in with support for recoverability, which is discussed in the next
section.
15.1.4 Recoverability
Recoverability is the ability of an active Message Exchange to be recovered during restart recovery to some
consistent point in it's lifetime. This would normally involve either persisting a Message Exchange or using
finer grain transactions to save the state of the Message Exchange.
15.1.5 Secrecy
Secrecy is the protection of information from being disclosed to outside parties. This is a basic requirement in
the financial industry, and often required in many other industries. In the NMR this comes about if the NMR
uses external storage in the implementation of transactions or persistence. The basic approach to solving this
problem is to encrypt any user data stored on external storage. This is an implementation problem, and not one
directly addressed by JBI.
15.2 Reliability in Message Exchange

The following sections show how reliable message delivery can be accomplished using the NMR API's for each
of the communication patterns.
Assumptions:
• Messages are idempotent
• If the initiator doesn't receive an end-to-end indication of completion (success/failure) of a communications
primitive, then the initiator will retry the communications primitive.
• If the servicer must retain some persistent result of the operation, the servicer must persist the result before
responding.
• Message Exchanges have a unique identifier.
• Any Message Exchange identifier saved during normal processing should be deleted at restart of the JBI
component.
This is mostly equivalent to an at-least-once message delivery mechanism.
15.2.1 One-way with Fault

Reliable communications protocol handlers often provide mechanisms for assuring delivery of an inbound
message to the application. Failure to successfully deliver the message will result in retries. Such protocols are
often realized as persistent message queues, as depicted in the message sequence chart below.
Stateful service engines use a persistent store to retain state over system shutdowns. To assure reliable message
transfer from the reliable messaging queue to the SE's persistent state store, the message exchange should not be
ended (with status exchange) until the message (or the results of processing the message) are persisted by the
SE.
Figure 34 Reliable One-way MEP with Fault Message Sequence Chart
Notes:
1. Code in or attached to BC queues a message for delivery to the BC. It expects that this information is
persisted. Once on the queue it should never be removed until step 8 has been reached. This guarantees that
the message will at least be sent once.
2. The BC picks a message to attempt delivery.
3. BC normalizes the message, and sends it to NMR.
4. SE accepts message from NMR
5. SE saves message. The SE could also check to see if the message has been seen before if follow-on logic
can't tolerate duplicate messages.
6. SE sends status to the NMR. SE can reject the message (e.g., structural, content or age problem) or accept
it, in either case the outcome is returned to the initiator.
7. BC accepts status from the NMR.
8. BC removes message from the delivery queue. After this point in time no attempt to redeliver the message
will be made.
15.2.2 Request-Response
Notes:
Figure 35 Reliable Two-way Exchange Message Sequence Chart
1. Code in or attached to BC queues a message for delivery to the BC. It expects that this information is
persisted. Once on the queue it should never be removed until step 8 has been reached. The guarantees that
the message will at least be sent once.
2. The BC picks a message to attempt delivery.
3. BC sends the message to the NMR.
4. SE accepts the message from the NMR
5. SE saves the message and its response to the message. (The SE could also check to see if the message has
been seen before if follow-on logic can't tolerate duplicate messages.)
6. SE sends the response to NMR. SE can reject the message (e.g., structural, content or age problem) or
accept it, in either case the outcome is returned to the initiator.
7. BC accepts response from NMR.
8. BC saves response
9. BC sends status of response to NMR
10. SE get status from the NMR
11. SE can cleanup any leftovers since it has positive acknowledgment of acceptance.
12. BC performs any cleanup.
15.2.3 Request Optional-Response

The Request Optional-Response communication primitive is just a dynamic selection of either Robust One-Way
or Request-Response. The selection is detected when (in the examples) the SE returns a status (Robust One-
Way) or SE returns a response message (Request-Response).
15.3 Transactional Message Exchange

The following sections show how reliable message delivery can be augmented with transactions to increase the
reliability and reduce work that a caller of the NMR needs to perform.
15.3.1 One-Way
An example sequence of operations for an exchange initiator is shown below.
Figure 36 One-way Transactional Message Exchange
Notes:
1. Initiator (an SE or a BC) starts a transaction. It may use its own transactional resources.
2. Initiator creates and initializes a Message Exchange instance, and sets the transaction on the Message
Exchange properties.
3. Initiator sends the ME to NMR.
4. NMR enlists its own internal resource.
5. NMR saves the ME.
6. NMR delists its own internal resource
7. Initiator commits the transaction. The initiator could do some more work with its own resources before the
commit and after the send().
An example message sequence diagram for the servicer side of this scenario is shown below:
Figure 37
Notes: (This is the servicer side.)

1. Servicer calls accept() to get a ME.
2. NMR reads the ME transaction property, then enlists its resource manager in the transaction.
3. NMR gets the ME data persisted in the previous (initiator) example.
4. NMR delists its resource manager.
5. Initiator calls setStatus() to say that its finished with the ME. The initiator can enlist its own resources and
perform operations against these.
6. Initiator commits the transaction.
15.3.2 One-Way with Fault
Figure 38 Transacted One-way Exchange with Fault
Notes:
1. Initiator starts a transaction and enlists it local resource.
2. Initiator can work with the local resource and then send the ME.
3. Servicer calls except, the transaction has been switched to the servicer's thread.
4. Servicer does whatever it wants with the message. It can enlist and delist local resource it needed.
5. Servicer sends the status back.
6. Initiator accepts the status. The transaction context has been switched back to the initiator's accept() thread.
7. Initiator can do other work with its local transaction and the commits.
15.3.3 Request-Response
Figure 39 Transacted Two-way Message Exchange
The Request Response communications primitive is the one case that can't be made reliable in a practical
fashion. The next section on transactional message exchange will provide a solution for this case.
1. Initiator creates a transaction.
2. Initiator enlists its local resources in the transaction and sends the message.
3. Servicer accepts the ME and the transaction context moves to the servicer's accept() thread.
4. Servicer processes the request, enlisting its local resources into the transaction if it needs.
5. Servicer delists any local resources and sends the response.
6. Initiator accepts the response and the transaction context is switched to the initiator thread.
7. Initiator can use local resources and send the status to the servicer.
8. Servicer accepts the status. Transaction context is not available, probably not much to do here.
9. Servicer can do anything it likes but can't effect the transaction.
10. Initiator can use local resources and then delists and commits the transaction.
15.3.4 Request Optional-Response

Just like the reliable version of Request Optional-Response, this is like a dynamic selection of Robust One-Way
or Request-Response.
CHAPTER 16
References
[APACHE ANT]
Apache Software Foundation. Apache Ant. See http://ant.apache.org/.
[ESB]
David A. Chappell. Enterprise Service Bus. O’Reilly, 2004.
[JAX-P 1.3]
Jeff Suttor, Norm Walsh. JavaTM API for XML Processing (JAXP) 1.3. See http://jcp.org/en/jsr/
detail?id=206.
[JAX-P Tutorial]
Sun Microsystems, Inc. JAX-P Tutorial. See http://java.sun.com/webservices/docs/1.3/tutorial/doc/
IntroWS5.html.
[JAX-RPC 2.0]
Marc Hadley, Roberto Chinnici. The Java API for XML Based RPC (JAX-RPC) 2.0. Early Draft Review 2,
JCP, January 2005. See http://jcp.org/aboutJava/communityprocess/edr/jsr224/index2.html.
[JLS]
James Gosling, Bill Joy, Guy Steele, Gilad Bracha. The Java Language Specification 2.0. Book, Sun
Microsystems, Inc., 2000. See http://java.sun.com/docs/books/jls/.
[JMX 1.2]
Sun Microsystems. Java Management Extensions (JMX) 1.2. See http://java.sun.com/products/
JavaManagement/.
[JVM 2]
Tim Lindholm, Frank Yellin. The JavaTM Virtual Machine Specification, Second Edition. Book, Sun
Microsystems, Inc., 1999. See http://java.sun.com/docs/books/vmspec/2nd-edition/html/
VMSpecTOC.doc.html.
[RFC 2119]
Scott Bradner. Key words for use in RFCs to Indicate Requirement Levels. RFC, Internet Engineering Task
Force, March 1997. See http://www.ietf.org/rfc/rfc2119.txt.
[W3C XOP]
Martin Gudgin, Noah Mendelsohn, Mark Nottignham, Herve Ruellan. XML-binary Optimized Packaging.
Recommendation, W3C, January 2005. See http://www.w3.org/TR/2005/REC-xop10-20050125/.
References
[WS-I AP]
Chris Ferris, Anish Karmarkar, Canyan Kevin Liu. Attachments Profile 1.0. Profile, Web Services
Interoperability Organization, August, 2004. See http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-
2004-08-24.html.
[WSDL 1.1]
Erik Christensen, Francisco Cubera, Greg Meridith, Sanjiva Weerawarana. Web Services Description
Language 1.1. Member Submission, W3C, March 2001. See http://www.w3.org/TR/wsdl.
[WSDL 2.0]
Roberto Chinnici, Martin Gudgin, Jean-Jacques Moreau, Jeffrey Schlimmer, and Sanjiva Weerawarana.
Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language. Working Draft, W3C,
August 2004. See http://www.w3.org/TR/2004/WD-wsdl20-20040803.
[WSDL 2.0 Bindings]
H. Haas, P. Le Hégaret, J-J. Moreau, D. Orchard, J. Schlimmer, Editors. Web Services Description
Language (WSDL) Version 2.0 Part 3: Bindings. Working Draft, W3C, August 2004. See http://
www.w3.org/TR/2004/WD-wsdl20-bindings-20040803
[WSDL 2.0 Extensions]
Martin Gudgin, Amy Lewis, Jeffrey Schlimmer. Web Services Description Language (WSDL) Version 2.0
Part 2: Predefined Extensions. Working Draft, W3C, August, 2004. See http://www.w3.org/TR/2004/WD-
wsdl20-extensions-20040803/.
[XML 1.0]
Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, and Eve Maler. Extensible Markup Language (XML) 1.0
(Second Edition). Recommendation, W3C, October 2000. See http://www.w3.org/TR/2000/REC-xml-
20001006.
Index Bootstrap class loading
ordering rules 107
BOOTSTRAP_EXTENSION
of javax.jbi.management.MBeanNames 155
A BuildException
accept() in Ant tasks 86
of javax.jbi.messaging.DeliveryChannel 158
accept(long)
of javax.jbi.messaging.DeliveryChannel 159
C
activateEndpoint(QName, String) canDeployToComponent(String)
of javax.jbi.component.ComponentContext of javax.jbi.management.DeploymentService-
120 MBean 144
Activation Class Loading
service provider 29 defined 63
Activation, endpoint 29 delegation order 104
ACTIVE implementation behaviour 103
of javax.jbi.messaging.ExchangeStatus 162 Class Loading Ordering Rules
addAttachment(String, DataHandler) bootstrap 107
of javax.jbi.messaging.NormalizedMessage execution 105
186 class-path
AdminServiceMBean in jbi.xml, use of 67
of javax.jbi.management 136 cleanUp()
Ant Script Support 86 of javax.jbi.component.Bootstrap 114
Ant Task close()
jbi-deploy-service-assembly 91 of javax.jbi.messaging.DeliveryChannel 159
jbi-install-component 87 Component
jbi-install-shared-library 89 of javax.jbi.component 116
jbi-list-binding-components 94 restart 100
jbi-list-service-assemblies 95 service description SPI 44
jbi-list-service-engines 92 start 99
jbi-list-shared-libraries 95 Component (interface)
jbi-shut-down-component 90 use of 98
jbi-shut-down-service-assembly 92 Component Context
jbi-start-component 90 use of 101
jbi-start-service-assembly 91 Component Installation Service 72
jbi-stop-component 90 Component Life Cycle
jbi-stop-service-assembly 92 defined 63
jbi-undeploy-service-assembly 91 extension 75
jbi-uninstall-component 89 management 74
jbi-uninstall-shared-library 89 Component Uninstallation
management 78
COMPONENT_LIFE_CYCLE_EXTENSION
B of javax.jbi.management.MBeanNames 155
Binding Type ComponentContext
for service engine (WSDL) 57 of javax.jbi.component 119
Bootstrap ComponentLifeCycle
of javax.jbi.component 114 of javax.jbi.component 126
use of 98 use of 98
Bootstrap Class Loader ComponentLifeCycleMBean
defined 63 of javax.jbi.management 139
Index
component-name createRobustInOnlyExchange()
in jbi.xml, use of 68 of javax.jbi.messaging.MessageExchangeFac-
composite deployment tory 182
defined 60 CSD
composite service description 6 see composite service description 6
Composite Service Metadata
defined 61 D
connection
in jbi.xml, use of 68 DataHandler
Connection Metadata of javax.activation, as message attachments 41
service assembly, handling 80 deactivateEndpoint(ServiceEndpoint)
connections of javax.jbi.component.ComponentContext
in jbi.xml, use of 68 121
CONSUMER Delegation
of javax.jbi.messaging.MessageExchange.Role class loading 104
179 DeliveryChannel
Consumers, Service accept, use of 44
key concepts 21 closing, API 44
consumes key concepts 22
in jbi.xml, use of 69 of javax.jbi.messaging 158
createCustomComponentMBeanName(String) sending exchanges 43
of javax.jbi.management.MBeanNames 155 use of API 43
createExchange(QName, QName) Denormalization, defined 28
of javax.jbi.messaging.MessageExchangeFac- deploy(String)
tory 180 of javax.jbi.management.DeploymentService-
createExchange(URI) MBean 144
of javax.jbi.messaging.MessageExchangeFac- deploy(String, String)
tory 181 of javax.jbi.component.ServiceUnitManager
createExchangeFactory() 131
of javax.jbi.messaging.DeliveryChannel 159 Deployment
createExchangeFactory(QName) defined 60
of javax.jbi.messaging.DeliveryChannel 159 Deployment Descriptors
createExchangeFactory(ServiceEndpoint) described 65
of javax.jbi.messaging.DeliveryChannel 160 Deployment Life Cycle
createExchangeFactoryForService(QName) defined 63
of javax.jbi.messaging.DeliveryChannel 160 Deployment Service
createFault() management 78
of javax.jbi.messaging.MessageExchange 172 deployment, composite
createInOnlyExchange() defined 60
of javax.jbi.messaging.MessageExchangeFac- Deployment, unit
tory 181 defined 60
createInOptionalOutExchange() DeploymentException
of javax.jbi.messaging.MessageExchangeFac- of javax.jbi.management 141
tory 181 use of 107
createInOutExchange() DeploymentException(String)
of javax.jbi.messaging.MessageExchangeFac- of javax.jbi.management.DeploymentExcep-
tory 181 tion 142
createMessage() DeploymentException(String, Throwable)
of javax.jbi.messaging.MessageExchange 173 of javax.jbi.management.DeploymentExcep-
tion 142
Index
DeploymentException(Throwable) Execution Class Loader

of javax.jbi.management.DeploymentExcep- defined 63
tion 142 Execution Class Loading
DeploymentServiceMBean ordering rules 105
of javax.jbi.management 143
deregisterExternalEndpoint(ServiceEndpoint) F
of javax.jbi.component.ComponentContext
121 Fault
DONE of javax.jbi.messaging 164
of javax.jbi.messaging.ExchangeStatus 162
Duplicate Service Unit G
definition 78 getAsReference(QName)
Dynamic Endpoint References 36 of javax.jbi.servicedesc.ServiceEndpoint 192
getAttachment(String)
E of javax.jbi.messaging.NormalizedMessage
Endpoint 186
activation 29 getAttachmentNames()
Endpoint Activation of javax.jbi.messaging.NormalizedMessage
key concepts 22 186
Endpoint Reference getBindingComponents()
API 49 of javax.jbi.management.AdminServiceMBean
for internal endpoints 50 137
Endpoint References getClassPathElements()
Dynamic 36 of javax.jbi.component.InstallationContext
Endpoint Selection 128
implicit 34 getComponentByName(String)
Endpoints of javax.jbi.management.AdminServiceMBean
key concepts 26 137
Endpoints, external getComponentClassName()
defined 26 of javax.jbi.component.InstallationContext
Endpoints, internal 128
defined 26 getComponentName()
EPR of javax.jbi.component.ComponentContext
API 49 121
Dynamic 36 of javax.jbi.component.InstallationContext
for internal endpoints 50 129
equals(Object) getComponentsForDeployedServiceAssem-
of javax.jbi.messaging.ExchangeStatus 163 bly(String)
ERROR of javax.jbi.management.DeploymentService-
of javax.jbi.messaging.ExchangeStatus 163 MBean 145
Example getContent()
activation and invocation 50 of javax.jbi.messaging.NormalizedMessage
activation and service provision 53 186
component installation descriptor 70 getContext()
service assembly deployment descriptor 71 of javax.jbi.component.InstallationContext
ExchangeStatus 129
API, use of 46 getCurrentState()
of javax.jbi.messaging 162 of javax.jbi.management.LifeCycleMBean
154
Index
getDeliveryChannel() getInMessage()
of javax.jbi.component.ComponentContext of javax.jbi.messaging.InOnly 165
121 of javax.jbi.messaging.InOptionalOut 167
getDeployedServiceAssemblies() of javax.jbi.messaging.InOut 169
of javax.jbi.management.DeploymentService- of javax.jbi.messaging.RobustInOnly 188
MBean 145 getInstallationDescriptorExtension()
getDeployedServiceAssembliesForCompo- of javax.jbi.component.InstallationContext
nent(String) 129
of javax.jbi.management.DeploymentService- getInstallerConfigurationMBean()
MBean 145 of javax.jbi.management.InstallerMBean 151
getDeployedServiceUnitList(String) getInstallRoot()
of javax.jbi.management.DeploymentService- of javax.jbi.component.ComponentContext
MBean 146 123
getEndpoint() of javax.jbi.component.InstallationContext
of javax.jbi.messaging.MessageExchange 173 129
getEndpoint(QName, String) of javax.jbi.management.InstallerMBean 151
of javax.jbi.component.ComponentContext getInterfaceName()
122 of javax.jbi.messaging.MessageExchange 174
getEndpointDescriptor(ServiceEndpoint) getInterfaces()
of javax.jbi.component.ComponentContext of javax.jbi.servicedesc.ServiceEndpoint 193
122 getJmxDomainName()
getEndpointName() of javax.jbi.management.MBeanNames 156
of javax.jbi.servicedesc.ServiceEndpoint 193 getLifeCycle()
getEndpoints(QName) of javax.jbi.component.Component 116
of javax.jbi.component.ComponentContext getLogger
122 of ComponentContext, use of 103
getEndpointsForService(QName) getLogger(String, String)
of javax.jbi.component.ComponentContext of javax.jbi.component.ComponentContext
122 123
getEngineComponents() getMBeanNames()
of javax.jbi.management.AdminServiceMBean of javax.jbi.component.ComponentContext
137 124
getError() getMBeanServer()
of javax.jbi.messaging.MessageExchange 173 of javax.jbi.component.ComponentContext
getExchangeId() 124
of javax.jbi.messaging.MessageExchange 173 getMessage(String)
getExtensionMBeanName() of javax.jbi.messaging.MessageExchange 174
of javax.jbi.component.Bootstrap 115 getNamingContext()
of javax.jbi.component.ComponentLifeCycle of javax.jbi.component.ComponentContext
126 124
of javax.jbi.management.ComponentLifeCy- getOperation()
cleMBean 139 of javax.jbi.messaging.MessageExchange 174
getExternalEndpoints(QName) getOutMessage()
of javax.jbi.component.ComponentContext of javax.jbi.messaging.InOptionalOut 168
123 of javax.jbi.messaging.InOut 170
getExternalEndpointsForService(QName) getPattern()
of javax.jbi.component.ComponentContext of javax.jbi.messaging.MessageExchange 174
123 getProperty(String)
getFault() of javax.jbi.messaging.MessageExchange 174
of javax.jbi.messaging.MessageExchange 173 of javax.jbi.messaging.NormalizedMessage
Index
186
getPropertyNames()
I
of javax.jbi.messaging.MessageExchange 175 Identification
of javax.jbi.messaging.NormalizedMessage in jbi.xml, use of 66
186 Implicit Provider Endpoint Selection 34
getRole() In Optional-Out MEP
of javax.jbi.messaging.MessageExchange 175 defined 33
getSecuritySubject() init(ComponentContext)
of javax.jbi.messaging.NormalizedMessage of javax.jbi.component.ComponentLifeCycle
187 126
getService() init(InstallationContext)
of javax.jbi.messaging.MessageExchange 175 of javax.jbi.component.Bootstrap 115
getServiceAssemblyDescriptor(String) init(String, String)
of javax.jbi.management.DeploymentService- of javax.jbi.component.ServiceUnitManager
MBean 146 132
getServiceDescription(ServiceEndpoint) InOnly
of javax.jbi.component.Component 117 of javax.jbi.messaging 165
getServiceName() In-Only MEP
of javax.jbi.servicedesc.ServiceEndpoint 193 defined 31, 32
getServiceUnitManager() InOnly Message Exchange
of javax.jbi.component.Component 117 API 47
getState(String) InOptionalOut
of javax.jbi.management.DeploymentService- of javax.jbi.messaging 167
MBean 146 InOptionalOut Message Exchange
getStatus() API 47
of javax.jbi.messaging.MessageExchange 175 InOut
getSystemInfo() of javax.jbi.messaging 169
of javax.jbi.management.AdminServiceMBean In-Out MEP
137 defined 32
getSystemService(String) InOut Message Exchange
of javax.jbi.management.AdminServiceMBean API 47
137 install()
getSystemServices() of javax.jbi.management.InstallerMBean 152
of javax.jbi.management.AdminServiceMBean Installation
138 defined 60
getTransactionManager() Installation Descriptor
of javax.jbi.component.ComponentContext described 65
124 Installation Packaging 69
getWorkspaceRoot() Installation Service
of javax.jbi.component.ComponentContext component 72
124 shared library 72
specified 71
InstallationContext
H of javax.jbi.component 128
hard link use of 102
defined 35 InstallationServiceMBean
hashCode() of javax.jbi.management 149
of javax.jbi.messaging.ExchangeStatus 163 InstallerMBean
creation during component installation 72
of javax.jbi.management 151
Index
use during component installation 72 JBIException

installSharedLibrary(String) of javax.jbi 110
of javax.jbi.management.InstallationServiceM- use of 107
Bean 149 JBIException(String)
isBinding(String) of javax.jbi.JBIException 111
of javax.jbi.management.AdminServiceMBean JBIException(String, Throwable)
138 of javax.jbi.JBIException 111
isDeployedServiceUnit(String, String) JBIException(Throwable)
of javax.jbi.management.DeploymentService- of javax.jbi.JBIException 111
MBean 146 jbi-install-component
isEngine(String) Ant task 87
of javax.jbi.management.AdminServiceMBean jbi-install-shared-library
138 Ant task 89
isExchangeWithConsumerOkay(ServiceEnd- jbi-list-binding-components
point, MessageExchange) Ant task 94
of javax.jbi.component.Component 117 jbi-list-service-assemblies
isExchangeWithProviderOkay(ServiceEnd- Ant task 95
point, MessageExchange) jbi-list-service-engines
of javax.jbi.component.Component 117 Ant task 92
isInstall() jbi-list-shared-libraries
of javax.jbi.component.InstallationContext Ant task 95
129 jbi-shut-down-component
isInstalled() Ant task 90
of javax.jbi.management.InstallerMBean 152 jbi-shut-down-service-assembly
isTransacted() Ant task 92
of javax.jbi.messaging.MessageExchange 175 jbi-start-component
Ant task 90
J jbi-start-service-assembly
Ant task 91
java.applet - package 195 jbi-stop-component
javax.activation.DataHandler Ant task 90
normalized message attachments 41 jbi-stop-service-assembly
javax.jbi.messaging.sendSync Ant task 92
exchange property 43 jbi-undeploy-service-assembly
jbi.xml Ant task 91
class-path, use of 67 jbi-uninstall-component
component-name, use of 68 Ant task 89
connection, use of 68 jbi-uninstall-shared-library
connections, use of 68 Ant task 89
consumes, use of 69 JMX Remote
contents 66 and Ant tasks 86
identification, use of 66 JTA_TRANSACTION_PROPERTY_NAME
provides, use of 69 of javax.jbi.messaging.MessageExchange 172
service-assembly, use of 67
services, use of 69
service-unit, use of 67 L
shared-library, use of 67 Life Cycle, Component
jbi-deploy-service-assembly defined 63
Ant task 91 management 74
Index
Life Cycle, Deployment InOnly API 47

defined 63 InOptionalOut API 47
Life Cycle, Service Assembly InOut API 47
management 82 key concepts 24
Life Cycle, Service Unit of javax.jbi.messaging 171
management 81 ownership 45
LifeCycleMBean receiving API 44
of javax.jbi.management 153 RobustInOnly API 47
Link sending 43
hard, defined 35 transaction context API 46
soft, defined 35 MessageExchange.Role
standard, defined 35 of javax.jbi.messaging 179
Link Types MessageExchangeFactory
defined 80 creating 43
loadInstaller(String) of javax.jbi.messaging 180
of javax.jbi.management.InstallationServiceM- MessagingException
Bean 150 of javax.jbi.messaging 183
loadNewInstaller(String) use of 107
of javax.jbi.management.InstallationServiceM- MessagingException(String)
Bean 150 of javax.jbi.messaging.MessagingException
Loggers 103 184
MessagingException(String, Throwable)
M of javax.jbi.messaging.MessagingException
184
MBean MessagingException(Throwable)
JBI status and result string, defined 83 of javax.jbi.messaging.MessagingException
MBeanNames 184
of javax.jbi.management 155 Metadata
Message Exchange composite service, defined 61
addressing types 33
addressing, by service endpoint 34
addressing, by service name 34 N
addressing, by service type 34 Normalization, defined 28
changes to address properties 34 Normalized Message Router
routing, and service connections 35 API classes 42
routing, link style and 35 NormalizedMessage
Message Exchange Pattern attachments API 41
fault rule 27 attachments, API 39
Message Exchange Patterns content, API 39
APIs 45 detailed concepts 28
determining participant role 31 key concepts 22
four standard 30 of javax.jbi.messaging 185
In Optional-Out, defined 33 properties 40
In-Only 31 properties API 41
In-Only defined 32 use of API 39
In-Out, defined 32
Message Exchange Routing 33
MessageExchange
creating instances 43
elements of 27
Index
NormalizedMessage, processing models 28 internal endpoint reference 50

JBI MBean status/result string 84
O WSDL 1.1 Message Wrapper 40
Self-first Delegation
onInstall() class loading 104
of javax.jbi.component.Bootstrap 115 send(MessageExchange)
onUninstall() of javax.jbi.messaging.DeliveryChannel 160
of javax.jbi.component.Bootstrap 115 sendSync
exchange property, and 43
P sendSync(MessageExchange)
Packaging, Installation 69 of javax.jbi.messaging.DeliveryChannel 160
Packaging, Service Assembly 70 sendSync(MessageExchange, long)
Packaging, Service Unit 71 of javax.jbi.messaging.DeliveryChannel 161
Parent-first Delegation Service Assembly
class loading 104 connection metadata handling 80
PROVIDER deployment, management of 78
of javax.jbi.messaging.MessageExchange.Role undeployment, management 80
179 Service Assembly Deployment
Provider Endpoint management 78
implicit selection 34 Service Assembly Descriptor
provides described 65
in jbi.xml, use of 69 Service Assembly Life Cycle
management 82
Service Assembly Packaging 70
R Service Description
registerExternalEndpoint(ServiceEndpoint) restrictions 44
of javax.jbi.component.ComponentContext Service Invocation
125 and message exchange patterns 23
removeAttachment(String) Service Provider
of javax.jbi.messaging.NormalizedMessage activation 29
187 activation domain model 29
resolveEndpointReference(DocumentFrag- Service Unit
ment) duplicate, defined 78
of javax.jbi.component.Component 118 Service Unit Deployment
of javax.jbi.component.ComponentContext management 79
125 Service Unit Descriptor
Restart, Component 100 described 65
RobustInOnly Service Unit Life Cycle
of javax.jbi.messaging 188 management 81
RobustInOnly Message Exchange Service Unit Packaging 71
API 47 Service, Providers
Routing, Message Exchange 33 key concepts 21
service-assembly
S in jbi.xml, use of 67
ServiceEndpoint
Schema
of javax.jbi.servicedesc 192
Ant component list 93
services
Ant service assembly listing 96
in jbi.xml, use of 69
deployment descriptors 65
service-unit
installation descriptor 65
in jbi.xml, use of 67
Index
ServiceUnitManager shutDown()
of javax.jbi.component 131 of javax.jbi.component.ComponentLifeCycle
use during service unit deployment 79 127
setClassPathElements(List) of javax.jbi.management.LifeCycleMBean
of javax.jbi.component.InstallationContext 154
130 shutDown(String)
setContent(Source) of javax.jbi.component.ServiceUnitManager
of javax.jbi.messaging.NormalizedMessage 132
187 of javax.jbi.management.DeploymentService-
setEndpoint(ServiceEndpoint) MBean 147
of javax.jbi.messaging.MessageExchange 176 soft link
setError(Exception) defined 35
of javax.jbi.messaging.MessageExchange 176 standard link
setFault(Fault) defined 35
of javax.jbi.messaging.MessageExchange 176 start()
setInMessage(NormalizedMessage) of javax.jbi.component.ComponentLifeCycle
of javax.jbi.messaging.InOnly 166 127
of javax.jbi.messaging.InOptionalOut 168 of javax.jbi.management.LifeCycleMBean
of javax.jbi.messaging.InOut 170 154
of javax.jbi.messaging.RobustInOnly 189 start(String)
setInterfaceName(QName) of javax.jbi.component.ServiceUnitManager
setMessage(NormalizedMessage, String) of javax.jbi.management.DeploymentService-
of javax.jbi.messaging.MessageExchange 177 MBean 147
setOperation(QName) Start, Component 99
of javax.jbi.messaging.MessageExchange 177 STARTED
setOutMessage(NormalizedMessage) of javax.jbi.management.DeploymentService-
of javax.jbi.messaging.InOptionalOut 168 MBean 144
of javax.jbi.messaging.InOut 170 of javax.jbi.management.LifeCycleMBean
setProperty(String, Object) 153
of javax.jbi.messaging.MessageExchange 177 Status and Result Strings
of javax.jbi.messaging.NormalizedMessage defined 83
187 stop()
setSecuritySubject(Subject) of javax.jbi.component.ComponentLifeCycle
of javax.jbi.messaging.NormalizedMessage 127
187 of javax.jbi.management.LifeCycleMBean
setService(QName) 154
of javax.jbi.messaging.MessageExchange 177 stop(String)
setStatus(ExchangeStatus) of javax.jbi.component.ServiceUnitManager
Shared Library of javax.jbi.management.DeploymentService-
installation service 72 MBean 147
shared-library STOPPED
in jbi.xml, use of 67 of javax.jbi.management.DeploymentService-
SHUTDOWN MBean 144
of javax.jbi.management.DeploymentService- of javax.jbi.management.LifeCycleMBean
MBean 144 153
of javax.jbi.management.LifeCycleMBean
153
Index
T WS-I
attachments profile 1.0 39
toString()
transaction context X
for MessageExchange 46 XML-binary Optimized Packaging 39
XOP 39
U
undeploy(String)
of javax.jbi.management.DeploymentService-
MBean 148
of javax.jbi.component.ServiceUnitManager
133
Undeployment
service assembly, management 80
uninstall()
of javax.jbi.management.InstallerMBean 152
Uninstallation
component, managment 78
uninstallSharedLibrary(String)
of javax.jbi.management.InstallationServiceM-
Bean 150
unit deployment
defined 60
UNKNOWN
of javax.jbi.management.LifeCycleMBean
154
unloadInstaller(String, boolean)
of javax.jbi.management.InstallationServiceM-
Bean 150
V
valueOf(String)
W
W3C
XOP 39
WSDL
as used for service descriptions 44
WSDL 1.1
Message Exchange Properties 48
message wrapper schema 40
messages 40
WSDL Binding Type
for service engine 57
Colophon
This specification document was generated from a set of Java, FrameMaker, StarOffice, and HTML source
files. They were compiled using javadoc and the MIF Doclet.
The MIF doclet generates its output in MIF format, which is processed through Adobe FrameMaker, http://
www.adobe.com/products/framemaker (http://www.adobe.com/products/framemaker).
Colophon

JBI Specification

Uploaded by

Copyright:

Available Formats

JBI Specification

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JBI Specification

Uploaded by

Copyright:

Available Formats

Java™ Business Integration (JBI) 1.

Comments to: [email protected]

Sun Microsystems, Inc.

August 17, 2005 Java Business Integration 1.0 Final Release iv

August 17, 2005 Java Business Integration 1.0 Final Release v

4 Architecture of the JBI Environment ........................................................ 11

5 Normalized Message Router ....................................................................... 21

7 Component Framework .............................................................................. 97

8 javax.jbi ...................................................................................................... 109

9 javax.jbi.component .................................................................................. 113

10 javax.jbi.management ............................................................................... 135

11 javax.jbi.messaging .................................................................................... 157

12 javax.jbi.servicedesc .................................................................................. 191

13 Almanac ...................................................................................................... 197

16 References ................................................................................................... 215

August 17, 2005 Java Business Integration 1.0 Final Release ix

August 17, 2005 Java Business Integration 1.0 Final Release x

1.1 Changes Since the Public Draft Review

August 17, 2005 Java Business Integration 1.0 Final Release xi

August 17, 2005 Java Business Integration 1.0 Final Release 1

2.3 Target Audience

August 17, 2005 Java Business Integration 1.0 Final Release 2

Prefix Namespace Description

2.6 Expert Group

August 17, 2005 Java Business Integration 1.0 Final Release 3

• TIBCO Software Inc. – Scott Vorthmann

2.7 Status of this Document

August 17, 2005 Java Business Integration 1.0 Final Release 4

Figure 1 Plug-in Construction of a System

Figure 2 Mediated Message Exchange: high-level message sequence chart

August 17, 2005 Java Business Integration 1.0 Final Release 5

August 17, 2005 Java Business Integration 1.0 Final Release 6

3.2 Rationale & Assumptions

August 17, 2005 Java Business Integration 1.0 Final Release 7

3.4 Relationship to other Specifications and Technologies

August 17, 2005 Java Business Integration 1.0 Final Release 8

3.5.1 Engine Developers

3.5.2 Binding Developers

3.5.3 JBI Environment Providers

3.5.4 J2EE™ Platform Providers

3.5.5 JBI Application Developers

August 17, 2005 Java Business Integration 1.0 Final Release 9

August 17, 2005 Java Business Integration 1.0 Final Release 10

4.1 WSDL-based Messaging Model

August 17, 2005 Java Business Integration 1.0 Final Release 11

Figure 3 WSDL Component Model Schematic

discussed in the following subsections.

4.1.1 Abstract Service Model

August 17, 2005 Java Business Integration 1.0 Final Release 12

4.1.2 Concrete Service Model

4.2 Normalized Message

August 17, 2005 Java Business Integration 1.0 Final Release 13

4.3 High-Level Architecture

Figure 4 Top-level view of the JBI architecture

August 17, 2005 Java Business Integration 1.0 Final Release 14

4.4 Normalized Message Exchange

Figure 5 External Service Consumer Message Processing Overview

a bidirectional delivery contract for message reception and delivery.

August 17, 2005 Java Business Integration 1.0 Final Release 15

Figure 6 External Service Provider Message Processing Overview