[
https://issues.apache.org/jira/browse/WODEN-120?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
John Kaputin closed WODEN-120.
------------------------------
> readWSDL methods should return Description not DescriptionElement
> -----------------------------------------------------------------
>
> Key: WODEN-120
> URL: https://issues.apache.org/jira/browse/WODEN-120
> Project: Woden
> Issue Type: Improvement
> Components: Parser
> Reporter: John Kaputin
> Assigned To: John Kaputin
> Fix For: M7
>
>
> I propose changing the WSDLReader API so that all readWSDL methods return a
> Description component instead of DescriptionElement.
> So the WSDLReader methods:
> DescriptionElement readWSDL(...)
> become
> Description readWSDL(...)
> Description is the top level interface of Woden's Component API which
> represents the WSDL Component model, while DescriptionElement is the 'top' of
> the Element API which represents the WSDL XML infoset. This change will
> reflect the intention of the WSDL 2.0 spec, which is focussed on the WSDL
> Component model, not the underlying XML infoset, in its discussion of WSDL
> data structures, data relationships, semantic behaviour and assertions. This
> focus is reflected in Woden, so to take full advantage of WSDL 2.0 the Woden
> user needs the Component API, not the Element API. In fact, certain WSDL 2.0
> features such as Interface inheritance are only fully supported in the
> Component API. The Element API really just provides a WSDL view of the XML
> infoset, but does not support all of the semantic behaviour defined for the
> WSDL Component model.
> Currently, after calling a readWSDL method, the user must then call the
> DescriptionElement.toComponent() method to get a Description with which to
> make full use of WSDL 2.0. It would be more useful to most WSDL 2.0
> consumers if these readWSDL methods returned a Description instead. If a user
> does need to access the WSDL XML infoset, they can call
> Description.toElement() to get a DescriptionElement. In fact, they can call
> toElement() on any Component to get the corresponding Element.
> Note also that because of the 'flattened' abstraction provided by the WSDL
> Component model, the toComponent() method only exists on DescriptionElement,
> not on other interfaces in the Element API. If a user gets a
> DescriptionElement from readWSDL and starts traversing the WSDL tree using
> the Element API, then realizes they need something from the Component model,
> they must still have a reference to the DescriptionElement so they can call
> its toComponent() method - they can't just call toComponent() from wherever
> they are in the Element API. And then they will probably need to traverse the
> WSDL again via the Component API to the required point. Better for them to
> work with the Component API by default via Description and explicitly change
> to the Element API if required (remembering of course that toElement() can be
> called from any Component).
> Returning Description rather than DescriptionElement will minimize the risk
> that users might navigate down a WSDL import hierarchy via the Element API,
> then call toComponent() on a 'nested' DescriptionElement. This can be done,
> but toComponent() is really intended to be used only on the top level
> DescriptionElement because it is this root <description> element that most
> likely has the appropriate visibility of all of the WSDL content necessary to
> correctly resolve the infoset to a 'useful' Component model. Although
> toComponent() called on a nested DescriptionElement will return a Description
> based on that point of the WSDL infoset, it might not be particularly useful
> and might be confusing to the Woden user.
> There may be WSDLReader Use Cases that do require a DescriptionElement,
> rather than a Description component (e.g. a WSDL editor tool parsing a WSDL
> document to modify its content). However, we have not addressed these yet and
> as our current focus and development effort is on parsing WSDL documents into
> the WSDL component model, I think our existing readWSDL methods should
> reflect this. We can always add methods to the WSDLReader API later if and
> when we need to support other Use Cases.
> As mentioned in the other WSDLReader API change proposed by WODEN-119, we
> have not yet declared the Woden API 'stable'. This will happen with a 1.0
> release, in the meantime our Milestone releases are subject to API change.
> Because this proposal only changes the return types (not the method
> arguments), this change cannot be accomplished with a deprecation strategy
> where the old and new method signatures co-exist in the next Milestone
> release. It might be necessary in this case to actively publicize the change
> via the mailing list and liaise with known users (e.g. Axis2) prior to M7,
> then simply change the method signatures for the M7 release.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
