[jira] Assigned: (WODEN-120) readWSDL methods should return Description not DescriptionElement

["John Kaputin (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/WODEN-120?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

John Kaputin reassigned WODEN-120:
----------------------------------

    Assignee: John Kaputin

> 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.
-
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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org