Template Version: @(#)onepager.txt 1.34 07/08/27 SMI
Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Sierra CAPS HTTP Binding Component
1.2. Name(s) and e-mail address of Document Author(s)/Supplier:
Sherry Weng. sherry.weng@sun.com
1.3. Date of This Document:
August 07, 2007. Updated 4/6/2008 by Tom Childers.
2. Project Summary
2.1. Project Description:
HTTP BC is a binding component that implements the SOAP and HTTP
bindings based on WSDL 1.1 specification. It provides external
connectivity over HTTP protocol in a JBI 1.0 compliant
environment. HTTP BC can take on the role of either a service
consumer or service provider in a JBI environment. It appears to
provide a web service to an external client when it is a service
consumer, and acts as a proxy to an external web service when it
is a service provider in JBI container.
Design time tools provided in NetBeans can be used to help create
WSDL files with proper SOAP or HTTP extensions. External
communication details can be defined via properties available in
SOAP or HTTP extensibility elements.
HTTP BC along with service engines such as BPEL, XSLT, workflow
SE can be orchestrated together to solve business problems. A
service unit will be created for each component involved. The
service unit for HTTP BC will include all the information the BC
needs to handle the service endpoints - WSDL(s), XSD(s) and
jbi.xml etc.
A good amount of composite application involving HTTP BC
leverages the SOAP/HTTP support the BC provides, however, the BC
is also capable to support XML/HTTP with basic HTTP GET/POST
operations.
Transport layer security is supported in HTTP BC. This includes
SSL, Basic Authentication and proxy server authentication. SOAP
message security (WS-Security) and other WS-* features,such as
Web Service Reliable Messaging and MTOM are also available in
HTTP BC through JAX-WS and WSIT integration.
2.2. Risks and Assumptions:
No risks percieved as yet.
3. Problem Summary
3.1. Problem Area:
Two issues with accessing WS-* features available in HTTP BC:
1. WS policy extensions need to be added to the WSDls manually
2. WS-* features are not available when HTTP BC is a web service
client.
3.2. Justification:
1. Tooling support is not available to
configure web service attributes in JBI projects
2. WSIT requires additional client configuration files. WSIT
implementation is currently very specific to Java EE web
services when it comes to loading these files.
4. Technical Description:
4.1. Details
4.1.1. Packaging
HTTP BC is packaged as a JSR 208 component archive. A component
archive is a JAR or ZIP file packaged in accordance with the
'Installation Packaging' requirements defined in the JSR 208
specification. The HTTP BC archive (httpbc.jar) contains an
installation descriptor (jbi.xml) and a set of jar files the BC
implementation depends on. The installation descriptor contains
the basic information about the BC: component name, component
class name, component classpath, bootstrap class name, bootstrap
class path and default configurations when the component is
installed. The archive also includes meta data information about
the default configurations (componentConfiguration.xsd and
componentConfiguration.xml). The information contained in these
files will be used to allow component properties editors (both
in NetBeans and Glassfish admin console) to render each
configuration properly.
The packaging structure of the HTTP BC follows:
httpbc.jar
/META-INF
jbi.xml
Manifest.mf
componentConfiguration.xsd
componentConfiguration.xml
/lib
httpsoapbcimpl.jar
componentsl.jar
resolver.jar
wsdl4j.jar
4.1.2. Installation
The HTTP BC comes pre-installed in Glassfish and NetBeans Enterprise
Pack 6.0. The BC fully implements the JSR 208 SPI for component
installation and uninstallation, so a user can install/uninstall the
component through standard JSR 208 interfaces using its component
archive (httpbc.jar).
4.1.3. Startup
The lifecycle of the HTTP BC is controlled by the JBI framework.
The HTTP BC implements the JBI ComponentLifeCycle interface,
which includes methods to start, stop, and shutDown the
component. These methods are called when one attempts to start
or stop a component through the management tools.
Optimizations in the JBI runtime allow the HTTP BC to remain in
a SHUTDOWN state until it is targeted by a service assembly
deployment, at which point it is initialized and started. This
serves as a form of lazy initialization - the component does not
consume any system resources if it is not being used. Lazy
initialization is handled inside the JBI runtime and does not
require any support from the HTTP BC itself.
4.1.3. Administration
Installation, deployment, and lifecycle management are handled
through the standard JSR 208 SPIs implemented by the HTTP BC.
In addition to the standard administration interfaces, the HTTP
BC exposes an MBean interface
(com.sun.jbi.httpsoapbc.configuration.RuntimeConfigurationMBean)
for runtime configuration of the component.
4.1.4 Transactions.
HTTP BC does not participate in transactions.
4.1.5 HTTP BC Service Units.
At present when a user composes a composite application, he needs to
include service units for all involved target components in the service
assembly.
Description of the packaging
----------------------------
The contents of the service assembly(TravelReservation.zip) would
look like the following. StockWSApplication.jar is a HTTP BC app.
.
./META-INF
./META-INF/MANIFEST.MF
./META-INF/jbi.xml
./sun-http-binding.jar
./TravelReservation.jar
The content of META-INF/jbi.xml of the service assembly would
contain the follwing service unit information for a HTTP BC application.
CompositeApp3-sun-http-binding
Represents this Service Unit
sun-http-binding.jar
sun-http-binding
The StockWSApplication.jar is the HTTP BC application.
The HTTP BC application, in it's META-INF directory will contain
the jbi.xml for the service unit as per JSR 208 spec.
The exploded SU (StockWSApplication.jar) looks like the following:
./META-INF
./META-INF/MANIFEST.MF
./META-INF/jbi.xml
./TravelReservation.wsdl
The content of META-INF/jbi.xml for the SU looks like the following:
All resources (jbi.xml, imported WSDLs and XSDs) are packaged in
the service unit jar file. Information about the service
endpoints can be retrieved from the jbi.xml. This informs the
BC whether it needs to provision or consume an endpoint. HTTP
BC also retrieves external communcation information from the
relevant WSDL extensibility elements.
4.2. Bug/RFE Number(s):
4.3. In Scope:
1) Supports WSDL 1.1 and SOAP 1.1 specs
2) Supports SOAP and HTTP binding from WSDL 1.1 spec
3) Follows WS-I 1.0 conventions and some support for
non-conforming components
4) Supports Document and RPC style web services
5) Supports common convention of WSDL retrieval
via ?WSDL
6) Supports XML catalogs following the OASIS Committee spec
7) Uses the application server's HTTP server - Grizzly
8) Uses Asynchronous I/O (NIO) to service 1000s of concurrent
incoming requests
9) Supports JBI service unit deployment to define the web services to
provision or consume
10)Makes use of WSDL extensibility elements (SOAP and HTTP) to define
external communication details
11)Supports clustering of HTTP BC
12)Supports HTTP load balancing and failover
13)Supports "environment variables"
14)Full support of soap-encoding including sparse arrays
15)Full integration with JAX-WS for SOAP/HTTP and XML/HTTP messaging
16)Support transport level security - SSL, Basic Authentication,
and proxy server authentication
17)Support BC-BC communications
4.4. Out of Scope:
1) Full support of REST style services
2) SOAP attachments
3) MIME bindings
4) Persistence for reliable messaging
5) Payload data validation against XML schema
6) WSDL 2.0 and SOAP 1.2 based communication
4.5. Interfaces:
4.5.1 Exported Interfaces
1. Interface:
JSR 208 Component SPI
Stability:
Committed
Comments:
http://jcp.org/en/jsr/detail?id=208
2. Interface:
com.sun.jbi.httpsoapbc.configuration.RuntimeConfigurationMBean
Stability:
Uncommitted
Comments:
Exposes a number of r/w component level configuration properties
3. Interface:
?WSDL
Stability:
Committed
Comment:
Retrieval of WSDL documents for deployed service endpoints
using standard ?WSDL interface
4.5.2 Imported interfaces
1. Interface:
JSR 208 API
http://jcp.org/en/jsr/detail?id=208
Stability:
Committed
Comments:
Implementation provided by JBI runtime.
2. Interface:
WSDL4J
http://sourceforge.net/projects/wsdl4j
Stability:
Committed
Comments:
Packaged inside component archive.
3. Interface:
Interface: Apache Resolver
Stability: Committed
Comments: http://xml.apache.org/commons/components/resolver
4. Interface:
Java EE 5 API
http://jcp.org/en/jsr/detail?id=244
Stability:
Committed
Comments:
Implementation provided by Glassfish.
5. Interface:
Grizzly
https://grizzly.dev.java.net/
Stability:
Committed
Comments:
Implementation provided by Glassfish.
6. Interface:
JAX-WS (http://jcp.org/en/jsr/detail?id=224)
com.sun.xml.ws.api
Stability:
Committed
Comments:
Implementation provided by Glassfish.
7. Interface:
JAX-WS (http://jcp.org/en/jsr/detail?id=224)
com.sun.istack.NotNull
com.sun.xml.ws.transport.http.HttpAdapter
com.sun.xml.ws.transport.http.WSHTTPConnection
Stability:
Uncommitted
Comments:
Implementation provided by JAX-WS and integrated into Glassfish.
While these interfaces are not part of a public contract, the
HTTP BC and JAX-WS teams are in close collaboration to evolve this
to a committed interface in the next release of Glassfish. The
HTTP BC ships as an integrated component of Glassfish, so we do not
anticipate any incompatiblity issues.
4.6. Doc Impact:
This is a new product, and a user guide regarding utilization of
the HTTP BC must be provided.
4.7. Admin/Config Impact:
The HTTP BC does not introduce any special administration or
configuration requirements. It is managed in an identical
fashion to the rest of the components shipping with JBI support
in CAPS 6.
4.8. I18N/L10N Impact:
All user-visible messages are stored in localizable resource
bundles. The HTTP BC can be localized by adding locale-specific
resource bundles to the component's classpath.
4.9. Packaging & Delivery:
See section 4.1.1.
4.10. Security Impact:
Passwords required in the Policy extensibility elements need to
be defined as an environment variable token. Password entries
will be masked using the BC's environment variable properties
editor in NetBeans or Glassfish admin console.
4.10.1 Security configuration:
There is no security configuration or issue specific to HTTP BC.
4.11. Compatibility Impact
N/A
4.12. Dependencies:
The HTTP BC must be installed in a JSR 208 compliant JBI runtime.
5. Reference Documents:
LSARC/2007/427 Sierra CAPS Base Components
http://sac.sfbay/LSARC/2007/427
LSARC/2007/512 Sierra NetBeans plug-ins
http://sac.sfbay/LSARC/2007/512
LSARC/2007/513 Sierra CAPS Installer
http://sac.sfbay/LSARC/2007/513
LSARC/2008/142 Sierra CAPS JBI Runtime ARC Case
http://sac.sfbay/LSARC/2008/142
JSR 208 Specification
http://jcp.org/en/jsr/detail?id=208
6. Schedule:
6.1. Projected Availability
HTTP BC will be released as part of the Sierra, CAPS 6.0,
scheduled for GA release in June, 2008.