signUrl returns a URI

[jboynes]

Changes Storage#signUrl to return a URI rather than a URL as the value is typically given to another client to use rather than being resolved by the calling application.

[jgeewax]

Just curious -- maybe I'm a n00b here -- what is the main difference here?

[jboynes]

There's more detail in the Java API doc for URI - see the sections on "URIs, URLs, and URNs."

To summarize though, URI was introduced as a way to identify things whereas URL is used to access things. To quote the doc, "a URL is a structured string that supports the syntactic operation of resolution as well as the network I/O operations of looking up the host and opening a connection to the specified resource."

The main use-case this method for generating a string to pass it to someone else so that they can access the stored object without needing to sign in. As such, it's generating an identifier to hand off and does not need the additional functionality for opening connections etc.

If by some chance they do need that locally, it's trivial to convert a URI to to URL using its toURL() method.

[coveralls]

Coverage remained the same at 64.71% when pulling 11ce83c on jboynes:signing_generates_uri into 0cd6f98 on GoogleCloudPlatform:master.

[jgeewax]

Got it -- and most of the time, the signed URL we generate is passed along to others who then use that to access.

So on our side, we're identifying, and others would be accessing. Sound right?

[coveralls]

Coverage remained the same at 64.71% when pulling 11ce83c on jboynes:signing_generates_uri into 0cd6f98 on GoogleCloudPlatform:master.

[aozarov]

Both serialize and can transform to one another. Indeed Java URL implementation also provides functionality such as get the resource but the main reason I used it (vs URI) is that I feel it is much more popular/known (for various reasons including that URI came later) and corresponds to the GCS naming that is using URL.

When I search google "what is URL" or "what is URI" I get:

• URL ... "A URL is the fundamental network identification for any resource connected to the web"...
• URI ... "string of characters used to identify a name of a resource"..

So I think the main difference is that URL is more specific about being a "web" resource, which
is a better (more constraint) description in this case. Is the main argument against it is that in
Java they also chose to provide functionality to it? If so, I would have still kept it as URL (for naming
consistency and being more specific).

@jgeewax I don't have strong opinion in this case. Do you?
If we go with URI should we also update other part of the method (method name, java doc mention URL)...

[jgeewax]

If the distinction is as @jboynes said in his first comment, I agree that URI is the right choice. I also should note that AWS is using URIs also (take a look at AmazonS3URI)

[jgeewax]

I also agree that this PR should include changes to swap other uses of URL -> URI (if there are any).

[eamonnmcmanus]

From a practical standpoint, the java.net.URL class dates from the earliest versions of Java and is rubbish, so I would say that in general java.net.URI is preferred regardless of whether the thing in question is really a URI or a URL. But in that case I think the method name and documentation should also say URI. Otherwise it will be confusing.

[jboynes]

Removed use of URL from the doc and renamed the method.

[aozarov]

We decided to keep the URL. see #14 for more details.