OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

sca-bindings message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [sca-bindings] Use cases for HTTP binding

Hi Simon,

Comments inline.


On Sep 2, 2010, at 3:45 PM, Simon Holdsworth wrote:


Thanks for the response.  So if I'm understanding correctly you're saying we could have an SCA service with:
  • binding.http
  • interface.java referring to a Java interface that has JAX-RS annotations

And that the binding.http would derive the mapping from URLs to operations in the Java interface from those annotations....?  

Not quite, if I understand you correctly. The JAX-RS annotations would drive (among other things), HTTP verbs, path mappings, content types, and parameter mappings.  For example:

public interface JsonMessageService {

    public void create(Message message) ;

    public Message retrieve(@PathParam("id") Long id);

    public Response delete(@PathParam("id") Long id);


I guess in that case my concern would be that the interface definition in this case would most likely make no sense for any other binding type.  If we had interface.wsdl there then we would either have to define binding.http elements/attributes or WSDL annotations to duplicate what's in JAX-RS.  I had been working under the assumption that this would be done through binding configuration rather than interface annotation.  We don't have that concept in the JMS or JCA bindings for instance - there we have elements in the binding which define the mapping from information used by the communications protocol to the operations and messages defined in the interface.

The above interface could also be used with binding.ws or binding.jms. 

Concerning WSDL, I'm not sure it is possible to express all JAX-RS semantics through WSDL 1.1. Assuming the latter could be done, how complex would mapping through binding configuration get? In the above example, it would involve doing the equivalent of mapping HTTP verbs to operations, URL parts to parameters, and handling media types?  

IN terms of how we satisfy these use cases, I think this is a key decision that needs to be made.

I appreciate that my examples should probably be rewritten to avoid using REST specifically.

I'm not sure how limiting our support to services initially due to alignment with JAX-RS actually solves the issue of related resources - unless our HTTP service capability does not permit this or requires that the construction of the related resource URLs is done explicitly within a component implementation.  I'm not sure if JAX-RS addresses this case.

I'm not sure I completely follow what your concern is here. Could you explain more? 

It certainly seems like we have identified a number of compelling use cases for HTTP enablement; I think the next steps should be:

1) write up the use cases in more detail, avoiding REST specifics, review and agree the use cases.
2) describe how those use cases could be satisfied within an SCA composite using binding.http and any interface or component implementation changes.
3) update the HTTP binding specification with the required changes.

Do we have a volunteer or two to collect/clean up/formally write up the use cases so that we can review and agree them?

I'm not sure I'm the best person to collect all of the use cases since I can't attend the binding meetings due to conflicts. However, I'm willing to help out writing up specific scenarios or doing other tasks that may be appropriate. Please let me know how I can help.

Regards, Simon

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair, AT&T and Boeing Lab Advocate
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com

From:        Jim Marino <jim.marino@gmail.com>
To:        OASIS Bindings <sca-bindings@lists.oasis-open.org>
Date:        28/08/2010 03:17
Subject:        Re: [sca-bindings] Use cases for HTTP binding


Sorry for the delay in responding but I have been on vacation. I have some comments inline.


On Aug 19, 2010, at 11:50 AM, Simon Holdsworth wrote:

As far as REST goes my preference would be that we provide a general-purpose HTTP binding which is flexible enough to be configured to interact with or provide RESTful services rather than standardising a REST-specific binding.  I don't think we should position this as a way to implement RESTful resources, rather as a way to extend the reach of SCA composites to access RESTful resources or be accessed from browser widgets.

FWIW, my interest in this has been several projects using SCA that needed to model APIs for clients outside of a domain. It was determined that a RESTful approach fit the use cases much better than Web Services (WS-*), so we used a proprietary binding based on JAX-RS. What appealed to those projects was a binding that allowed SCA services to be modeled as RESTful resources. I think this is an important use case for such a binding, as you outline below.  

Also, it may prove very difficult to define a generic binding that can map both POX and RESTful resources since they are so different. One option would be to create two different binding types. If that were the case, it could be argued that the "RESTful" binding was more "HTTP" than the POX one since it uses HTTP as a protocol...  

I agree with Bryan's comments regarding allowing more flexibility.  I would be wary of providing a binding which imposes a specific interface design approach though.   My expectation would be that exposing services from an SCA composite to be accessed via HTTP would generally use a specifically designed interface; accessing services via HTTP from an SCA composite may well need to be based on an existing interface not directly related to the HTTP resource.  If the resource dictated the interface it would become common for SCA composites to have to have a mapping component which translates between the established interface and the one that was created to fit in with the HTTP binding.

As far as JAX-RS goes, I think it would be useful to provide a consistent level of capability, but I don't see it as necessary to explicitly support JAX-RS.

For Java, if the binding is going to support using HTTP as a protocol (as opposed to tunneling a protocol over HTTP), it will need to either support JAX-RS or define a equivalent mapping from HTTP to Java types. JAX-RS does a good job and seems logical to adopt.

Here are a few specific use cases which would motivate flexibility required to support REST:

Access to RESTful resource:  I want to be able to retrieve some information about the current state of my business provided as an external RESTful resource to influence the behaviour of my composite.  The resource expects parameters supplied in the URL path, optional parameters in the query string, and returns an XML document.  I want to make the retrieval based on information I have within a complex data structure and set a particular element with the resulting value.

Provision of RESTful resource:  I want to be able to allow browser widgets access to a service that I provide from my composite that allows query/update of some aspect of the current state of my business process.  The browser widget supplies parameters in the URL path and may include a JSON document for update operations.  I want to design the interface for the service that I provide based on the set of operations I want to make available.

Expose a Java component which has JAX-RS annotations as an SCA java component with an HTTP service binding:  Not so sure about this one, but we might want to consider somehow automatically deriving the configuration for the SCA service binding.http from the JAX-RS annotations.   Note that we don't (to my knowledge) currently allow a JAX-WS annotated Java component to drive the configuration of a binding.ws on an SCA service.

My suggestion was to use JAX-RS to drive the mapping from HTTP to Java types in a way similar to how JAX-WS annotations are used to shape WSDL from a Java type. Interface types other than interface.java could use different means.  

In order to support an arbitrary mapping from interface to HTTP message I believe the following would be required at a minimum in terms of the binding configuration:

For the binding: a base URL, a default wireFormat and operationSelector.

For each operation in the interface:
  • a URL template which may be absolute or relative to the base URL.  The URL template may include replaceable parameters in the path or query string.  The syntax defined for JAX-RS seems as good as any to define the URL template.
  • a mapping from the replaceable parameters to elements in the input message.  This could be a direct mapping to top-level message parts, or a deeper mapping using XPath for instance.
  • an optional mapping from the HTTP body to an element in the input message for create/update operations, as above.
  • an optional mapping from the HTTP body to an element in the output message for retrieve operations, as above.
  • an optional specific wireFormat

Here I'm limiting the parameter mapping to path and query string.  I know JAX-RS allows other mappings including HTTP headers but I'm not sure those are recommended REST practice - the URL path should always identify the resource in the absence of other information.

One aspect of supporting REST in SCA that does cause concern for me is how we would support referenced resources.  Within the body of the XML or JSON document I just retrieved via my nice impl/protocol neutral interface, there may be additional URLs that point to referenced resources (the book's publisher, the queue's queue manager, the list of referenced documents, etc...).  How do I model those in my interface?  Should the binding automatically go get them too so that I can represent them as complex objects - in which case we have to worry about arbitrary linking and cycles?  Or do I need to have some endpoint reference or other veneer over them to avoid exposing the fact that I got this information via use of binding.http rather than some other binding?  Or just bite the bullet and have URLs in my interface - in which case how does my component then use that URL to go get that resource?   And when I return a document from a service which includes referenced resources, how do I construct the URLs for those resources so that they point to the correct SCA service binding (or other location)?

Having the binding handle hypertext in a generic way may be next to impossible as link semantics are often specific to the content type.

Related to this, specifying a binding for *consuming* REST  may be premature. JAX-RS does not yet define a client API, although several JAX-RS implementations such as Jersey and RESTEasy have proprietary ones. Presumably, something analogous would need to be done for SCA if the HTTP binding were to be used on references to consume RESTFul resources from Java components. It may be best to wait until JAX-RS defines a client API before this is tackled since such an API could be used as the reference type in Java.    


Regards, Simon

Bryan Aupperle <
aupperle@us.ibm.com> wrote on 13/08/2010 15:25:57:

> From: Bryan Aupperle <
> To: OASIS Bindings <
> Date: 13/08/2010 15:34

> Subject: Re: [sca-bindings] Use cases for HTTP binding

> This is a good start to the discussion.  Some additional thoughts/
> things to consider...
> For accessing an HTTP-based service:
> - This does not need not be limited to XML-based results.  The
> result could be JSON or similar (can be described with XSD+DFDL)
> - Many services are going to be able to return results in multiple
> formats.  The binding will need to indicate one.
> - There are several ways that request parameters are transmitted,
> part of the URL, query parameters, in the body of the request, etc.
> we will need to either limit or allow for the common patterns
> - What is the "scope" of a service (i.e. limit to just one shape of
> data or a set of related shapes)  This may impact the nature of the
> URL specified in the binding as well as the service interface
> For providing an HTTP-based service:
> - This should also include feeds and modifiable data (e.g. a PUT
> adds or modifies/replaces the input object)
> - Do we want to constrain the way request parameters are transmitted?
> - Same sort of "scope" questions as for accessing an HTTP-based service
> Overall question (not really related to the binding but more so to
> HTTP-based services): Can we define one or a small set of “generic
> interfaces” for basic HTTP-based service patterns?
> As Anish pointed out, on a recent call we need to be careful about
> labeling anything REST.
> Bryan Aupperle, Ph.D.
> STSM, WebSphere Enterprise Platform Software Solution Architect
> WW Center of Excellence for Enterprise Systems & Banking Center of
> Excellence Application Integration Architect
> Research Triangle Park,  NC
> +1 919-254-7508 (T/L 444-7508)
> Internet Address:

> From:
> Jim Marino <
> To:
> OASIS Bindings <
> Date:
> 08/09/2010 04:04 PM
> Subject:
> Re: [sca-bindings] Use cases for HTTP binding

> On Aug 4, 2010, at 2:06 AM, Eric Johnson wrote:
> I agreed to an action item to write up, with respect to the
> potential HTTP binding, the two use-cases I discussed in the
> conference call.  So here goes.

> Description
> Exploit an existing HTTP-based service that has XML-based result.  
> More specifically, a JAX-WS or Ruby-On-Rails service, wherein the
> URLs for the service are reasonably predictable.  Map that to a set
> of operations mapped to messages being exchanged
> Preconditions
> "Parameters" to request data are simple strings
> Every "read" request needed can be mapped to an HTTP GET
> WSDL portType is described with a small flat set of parameters on
> input and a single XML element upon return
> Certain HTTP status codes can be mapped to application level faults
> Authentication/authorization credentials are supplied at deployment,
> and/or TLS with bi-directional certification validation might be required.

> What happens:
> In binding the portType to an HTTP GET request, the child elements
> of the request operation get mapped to parameters on the URL.  
> Default mapping is element local name to parameter name.  Binding
> needs to specify a URL with substitution points.
> Root element of response document is the response element for the result.
> In case of an HTTP error code, where specified, a fault is mimicked
> for "replies."
> Post-conditions
> Invocations of the "reference" operation return the XML results
> mapped to the language mapping of said data structure


> Description:
> Stateful "monitor" of an service providing 1 or more atom feeds,
> supporting three operations "getNewEntriesForFeedFoo",
> "getLastNEntriesForFeedFoo", "getContentForFoo" - per Atom feed.
> Preconditions:
> Service that offers up one or more atom feeds
> Atom feeds are changing slowly enough that polling for data at lazy
> intervals (1 - 60 minutes) is sufficient
> Customer has a name for each URL.  Operations in the interface
> follow a known pattern like getNewEntriesForFeedFoo
> Customer has particular data that they're interested in from each
> feed, such as author, modification date, ID, other metadata
> What happens
> A service requests an update from a specific specific feed by
> calling getNewEntriesForFeedFoo (where "Foo" changes per feed)
> Post-conditions
> Returns a list of new entries, the list of the last N entries
> requested, or the content for the particular entry.

> Note, for this last case, it would be much more natural to define
> the interface with "interface.atom", wherein the relevant metadata
> would be flagged for each feed, and the content of the root element
> of a feed entry was established.  This would follow known mapping
> rules to map to a WSDL expression of the same, if that was required.
> Then again, I filed an issue for letting Assembly allow non-WSDL
> interface descriptions for a reason....
> On the service side, the one use-case I can think of is URL
> addressability of read-only service information.  This is
> essentially the reverse of the first use-case described above, with
> one additional caveat.  It may be desirable to map to multiple URLs
> (.xml, .rdf, .xhtml, .txt), so for the service side of this binding
> a natural thing, I think would be to specify an XSLT file correlated
> with a particular MIME type.  In the XML case, that might be added
> as a XSL processing instruction.
> None of these use-cases gets at all close to REST, but they seem
> like the might be useful in the abstract.  I've not got specific
> customer needs that are driving these ideas.
> -Eric.
> Eric,
> Has it been brought up to do a "REST" binding instead where
> operations are mapped to HTTP verbs and content is mapped to the
> content-type header instead? For Java implementation types, JAX-RS
> annotations could be used in a way similar to the way JAX-WS
> annotations are for WS-* protocols. Such an approach may prove to be
> more interoperable with other frameworks such as Ruby On Rails or
> .NET (which has something analogous to JAX-RS). I put REST in quotes
> since HATEOAS would likely not be accommodated in such a binding.
> Jim
> P.S. +1 on allowing non-WSDL interface descriptions.    

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]