[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-bindings] Use cases for HTTP binding
On Sep 9, 2010, at 3:13 PM, David Booz wrote:
> 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.
>
I agree they are language specific. However, my understanding is the JAX-RS API doesn't say much about databinding. It specifies content/media type, but that's different than databinding, which can be specified through JSON mapping, JAXB, etc.
Many of the JAX-RS annotations such as GET, POST, PUT, etc. would probably be analogous to the JAX-WS @WebMethod, with the obvious caveat that the semantics of the former bind Java operations to things such as HTTP verbs as opposed to tunneling a protocol over a transport such as HTTP (WS-*).
I think it would be good to be able to use JAX-RS with SCA, particularly since it is a really elegant way of handling remote communications.
Jim
> 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]