API: Deprecate ContentFile#path API and add location API which returns String

[amogh-jahagirdar]

ContentFile#path returns CharSequence instead of String. The original intention of this API returning CharSequence was to directly surface Avro UTF8 without any conversion, however for distributed cases the CharSequence needs to be converted into String since CharSequence itself isn't serializable. Furthermore, in terms of naming we tend to use location in other places like manifestListLocation or metadataLocation, also in FileIO. This change performs the following:

1. Deprecate path on ContentFile since callers need to convert the CharSequence to String for the majority of cases. This would be removed from the interface in 2.0
2. Add a String location() API to ContentFile which logically returns the same filePath but it will return String instead. An initial default implementation of location has been provided.

Over time up until 2.0 we can remove references to path and use location. After 2.0 implementations of ContentFile would need to implement location.

[flyrain]

It'd be nice to keep the name, but overloading could not apply to the return type.

[aokolnychyi]

I wonder whether we still want to keep the Hadoop Path reference here as it quite evolved over the years and we do not necessarily depend on Hadoop anymore.

[amogh-jahagirdar]

Good point, I was largely concerned if we didn't preserve this property of being suitable for a hadoop path at the API level, once path is deprecated, it may break the users that do rely on having this. But if we're saying that we don't really need to concern ourselves on maintaining this, we may not need to include it. cc @rdblue thoughts on this?

[amogh-jahagirdar]

Discussed with @rdblue @danielcweeks and here are some key points on why we shouldn't document anything related to hadoop:

1. Hadoop pathing doesn't work with storage systems like GCS
2. Locations are a super set of what can be represented in a hadoop path. Even today path API can return paths which simply cannot be represented in a hadoop Path.
3. The hadoop path normalization logic simply conflicts with absolute paths

So updated to remove this part of the comment. I'll leave the existing path API comment as is since it's being deprecated anyways.

[aokolnychyi]

I support this change. Internally, we always use String objects for serializability and most places that consume have explicit conversion to String already.

[amogh-jahagirdar]

THanks for reviewing @flyrain @nastra @aokolnychyi , I'll go ahead and merge