[
https://issues.apache.org/jira/browse/WODEN-120?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12465117
]
John Kaputin commented on WODEN-120:
------------------------------------
Extract from Minutes of weekly Woden call Tuesday 9th January 2007:
Discussed API changes to WSDLReader in WODEN-119 and WODEN-120
WODEN-119 is about passing wsdl uri to readWSDL methods as java.net.URI
instead of java.lang.String.
Arthur: could we just add new methods that take java.net.URI and leave the
methods with String args?
John: an original design goal was type safety in the API, so allowing only
URI args instead of String args means the user must ensure that the wsdl
uri argument is 'type safe' (i.e. in the correct format to create a
java.net.URI). It also achieves consistency across the API as everywhere
else java.net.URI is used to represent uris. The issue is not specifically
about avoiding the need to handle MalformedURLException within the reader.
Arthur: how do we handle API change without breaking existing users?
John: Add new readWSDL methods with URI args, deprecate existing methods
for M7 then remove them in the release that follows M7.
Arthur: agreed.
Graham: agreed.
Jeremy has already +1 via the mailing list.
WODEN-120 is about the readWSDL methods returning Description instead of
DescriptionElement.
We discussed the rationale as explained in the JIRA and agreed with this
proposal (John, Arthur, Graham).
Jeremy has already +1 via the mailing list.
Noted that as deprecation of existing methods won't work (i.e. it's just
the return type being changed), we will need to coordinate with Axis2 folks
on their building of a Woden SNAPSHOT jar for inclusion in the Axis2 build.
[action] John to coordinate this change with Axis2 / WSO2
> 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
> 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.
-
If you think it was sent incorrectly contact one of the administrators:
https://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
