+1 to this.
Cheers,
Jeremy
On 06/01/07, John Kaputin (JIRA) <[EMAIL PROTECTED]> wrote:
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
