| 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
|