You are viewing a plain text version of this content. The canonical link for it is here.
Posted to woden-dev@ws.apache.org by "John Kaputin (JIRA)" <ji...@apache.org> on 2007/01/06 04:49:27 UTC
[jira] Created: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org
Re: [jira] Created: (WODEN-120) readWSDL methods should return Description not DescriptionElement
Posted by Jeremy Hughes <hu...@apache.org>.
+1 to this.
Cheers,
Jeremy
On 06/01/07, John Kaputin (JIRA) <ji...@apache.org> 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: woden-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: woden-dev-help@ws.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org
[jira] Assigned: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
Posted by "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
[jira] Closed: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
Posted by "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 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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org
[jira] Commented: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
Posted by "John Kaputin (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/WODEN-120?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12465128 ]
John Kaputin commented on WODEN-120:
------------------------------------
I would like to implement this fix as soon as possible - I propose Thursday 18th January. Because it involves a change to the Woden API, I will try to coordinate this change with Axis2 and WSO2 (who are currently doing the WSDL 2.0 interop testing). The last Woden snapshot jar used by Axis2 is dated December, but I want to find out if they are doing daily Axis2 builds off Woden trunk and if so, get them to make the change at the same time. WSO2 will need to change their call to the readWSDL method.
The required code change involves receiving a Description back from the readWSDL method, rather than receiving a DescriptionElement and having to call its toComponent() method to get the Description. The rationale is in the previous comments in this JIRA.
So, for example:
DescriptionElement descElem = wsdlReader.readWSDL("someURL");
Description descComp = descElem.toComponent();
becomes:
Description descComp = wsdlReader.readWSDL("someURL");
If the WSDL infoset needs to be accessed via Woden's Element API, then just call the toElement() method on the Description component, or on any other component. E.g.:
DescriptionElement descElem = descComp.toElement();
InterfaceElement interfacElem = InterfacComp.toElement();
> 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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org
[jira] Resolved: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
Posted by "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 resolved WODEN-120.
--------------------------------
Resolution: Fixed
r499213. The API changed as described in previous comments, so that WSDLReader.readWSDL methods now return Description instead of DescriptionElement.
This change included fixing some bugs in OMWSDLReader.parseSchemaImport that had not surfaced previously because the OM implementation and test cases were only ever using DescriptionElement, but not Description.
> 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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org
[jira] Commented: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
Posted by "Jeremy Hughes (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/WODEN-120?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12463017 ]
Jeremy Hughes commented on WODEN-120:
-------------------------------------
+1 to this - like you say we need to ensure Axis2 change their usage of readWSDL as soon as we make this change. In fact the change to Axis2 needs to happen at the moment the Woden snapshot [1] and [2] is updated (which has been done by Dims in the past) ! Tricky to co-ordinate.
[1] http://ws.zones.apache.org/repository/incubator-woden/jars/
[2] http://people.apache.org/repo/m1-snapshot-repository/incubator-woden/jars/
> 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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org
[jira] Commented: (WODEN-120) readWSDL methods should return
Description not DescriptionElement
Posted by "John Kaputin (JIRA)" <ji...@apache.org>.
[ 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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org