[jira] Commented: (WODEN-119) readWSDL method args should be java.net.URI instead of String

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

    [ https://issues.apache.org/jira/browse/WODEN-119?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12465584 ] 

John Kaputin commented on WODEN-119:
------------------------------------

I have changed my mind on this issue and would like to cancel the JIRA without make the proposed API change to these readWSDL methods.  There are a few problems with using java.net.URI instead of String for the wsdlUri parameter:

1) It's not really a URI we are interested in, it's the URL because we need to use this method parameter to 'locate' the WSDL document. At least, the Woden implementation uses this parameter (whether it's a String or a URI) to create a URL to retrieve the WSDL document. 

2) URLs are a subset of URIs - all URLs are URIs, but the opposite is not true (e.g. URNs). It's possible with both String and URI that a value could be specified which is not a URL and causes a MalformedURLException...the use of java.net.URI over String doesn't avoid this possibility.

3) The java.net.URI class does not offer much functional advantage over String. It doesn't do any format validation based any protocol scheme specified in the URI (http:, file:, etc). It accepts anything as the scheme, whereas URL will reject anything it doesn't have a protocol handler for. It does exclude the use of characters that are illegal in URIs (e.g. ` { } @ = | \) and provides a URI-based structure (which we don't make use of), but not much else.

4) String is convenient from the client's perspective and given that the type safety argument for URI is not as strong as it appeared to be, a String parameter is better for the usability of the API. However, the method Javadoc should either state that the String value should be a valid URL or it should comment on the existing behaviour of accepting a file path and pre-pending the "file:/" scheme to convert it to a file URL. And the parameter name should be changed from wsdlUri to wsdlUrl. The use of String for specifying document locations seems to be a convention used in similar parser technologies too (XmlSchema, Xerces), but this may simply be historical (i.e. before java.net.*).

The most type-safe approach would be to use java.net.URL as the parameter type, rather than String, but that does require more effort in the client programming model. Before calling the WSDLReader API, the client would need to instantiate a URL object, which means converting a file path string into a file URL.  As Woden already has helper-functionality to do this it does not seem sensible to expect  clients to do it themselves.

One of my arguments for doing this change in the first place was the original Woden design decision to improve type safety by using java.net.URI to represent URIs rather than String. This is fine for xs:AnyURI types defined in WSDL 2.0 and represented in the Component and Element APIs but on reflection, that's different to the method parameter used in these readWSDL methods.

Unless anyone has any objections, I will leave the two readWSDL methods as they are with String parameters for the wsdl url.


> readWSDL method args should be java.net.URI instead of String
> -------------------------------------------------------------
>
>                 Key: WODEN-119
>                 URL: https://issues.apache.org/jira/browse/WODEN-119
>             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 the readWSDL methods that take a wsdl location uri argument use java.net.URI instead of String.
> So the WSDLReader methods:
>     readWSDL(String wsdlURI)
>     readWSDL(String wsdlURI, ErrorHandler errorHandler)
> become
>     readWSDL(URI wsdlURI)
>     readWSDL(URI wsdlURI, ErrorHandler errorHandler)
> One of our design goals for the Woden API was to consistently use java.net.URI instead of java.lang.String to represent URIs, so as to achieve a measure of type safety at the API boundary. Elsewhere the Woden API uses java.net.URI - the two readWSDL methods that take a String as the wsdl uri are the only exceptions and these are a left over from my early prototyping that was based on WSDL4J. Changing these two methods to take a java.net.URI argument will make the Woden API consistent in this regard and will make it more robust by ensuring the WSDL uri passed to the reader is correctly formatted as a URI (because the Woden client must instantiate the java.net.URI object).
> As discussed previously, we are delivering Milestone releases to get code out quickly to early adopters, but we have not yet declared the Woden API 'stable'. This will happen with a 1.0 release. However, to minimize disruption to existing Woden users, these two readWSDL methods could be changed via a deprecation strategy for M7 - that is, add the new method signatures to WSDLReader and deprecate the existing ones, then remove those deprecated methods for the release that follows M7.

-- 
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