[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-bindings] Use cases for HTTP binding
The JAX-RS annotations have always struck me as a language specific (i.e.
they are Java annotations) way of specifying the data binding and operation
binding aspects of integration, where SCA as two concepts called wireFormat
and operationSelection which are analogous.
Dave Booz
STSM, BPM and SCA Architecture
Co-Chair OASIS SCA-Policy TC and SCA-J TC
"Distributed objects first, then world hunger"
Poughkeepsie, NY (845)-435-6093 or 8-295-6093
e-mail:booz@us.ibm.com
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Jim Marino <jim.marino@gmail.com> |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|OASIS Bindings <sca-bindings@lists.oasis-open.org> |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|09/09/2010 08:18 AM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: [sca-bindings] Use cases for HTTP binding |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
Hi Simon,
Comments inline.
Thanks,
Jim
On Sep 2, 2010, at 3:45 PM, Simon Holdsworth wrote:
Jim,
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:
@Path("/")
@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public interface JsonMessageService {
@PUT
@Path("/message")
public void create(Message message) ;
@GET
@Path("message/{id}")
public Message retrieve(@PathParam("id") Long id);
@DELETE
@Path("message/{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.
Jim
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
Simon,
Sorry for the delay in responding but I have been on vacation. I have
some comments inline.
Jim
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.
Jim
Regards, Simon
Bryan Aupperle <aupperle@us.ibm.com> wrote on 13/08/2010 15:25:57:
> From: Bryan Aupperle <aupperle@us.ibm.com>
> To: OASIS Bindings <sca-bindings@lists.oasis-open.org>
> 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: aupperle@us.ibm.com
>
>
> From:
>
> Jim Marino <jim.marino@gmail.com>
>
> To:
>
> OASIS Bindings <sca-bindings@lists.oasis-open.org>
>
> 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]