Should we merge the functional object with the metadata objects.

[aozarov]

Current when possible we use the following pattern for google cloud resource:

XXX resource metadata - An immutable (using the standard builder pattern) and serializable class named XXXInfo with only data accessors.

XXX resource - An immutable, no serializable class pinned to a specific metadata and service implementation.

As both classes are immutable and as service can always be re-created via its options should we unify them and make the main service API always return the functional objects?

/cc @mziccard @ajkannan @mderka

[ajkannan]

I vote for unifying them, because then users would be less likely to get confused over the difference between an xxx and an xxxInfo.

[mziccard]

If we go this way, do we expect the user to always provide a service instance? E.g.:

Blob blob = Blob.builder(storage, BlobId.of("b", "n")).contentType("content").build();

This makes:

blob = storage.create(blob);

A bit redundant don't you think?

I don't think that having XXX and XXXInfo represents a problem from the usability standpoint but it would be better to have some feedback from the users.

[aozarov]

I don't think the first one should actually send a request to create the blob (hence, calling blob.exists() on it should return false if did not already exists).
The same way Blob blob = new Blob(storage, blobInfo) does not create it.

However, it may be nice to add to Blob an explicit create method (similar
to the other syntactic sugar method that we have in Blob).

I also think that having XXX and XXXInfo does not represent a problem (Info should be
considered as Metadata, though we picked "Info" for short) however I do wonder if unifying
them (at this point when we can re-constructor the original service) would not make the API
nicer (and more concise).

/cc @Capstan @mfschwartz @jtigani

[mfschwartz]

My thoughts:

• There's value in having a separate class for the metadata, because some GCS operations just examine/manipulate metadata without touching the data
• I don't get the point of shortening "Metadata" to "Info". Sure, it's fewer chars to type but (a) then users need to map (in their minds) between those names and the names we describe in the GCS documentation, and (b) many users develop with IDEs anyway, so the shorter name doesn't seem like it makes things much simpler.

[aozarov]

Thanks for your thoughts @mfschwartz.

Even now the functional Blob does not hold the content. It has a reference to the info and provides
methods to operate on the (specific) blob, including getting its content.

[mfschwartz]

Let me make the point about shortening "Metadata" to "Info" a bit more forcefully:

I think it makes sense for a library such as this to create new abstractions that make life easier for clients.
In contrast, I think it's a bad idea to use a different name for existing concepts just because you like shorter names or otherwise have a personal preference for the new name, because that negatively impacts consistency across the Cloud Platform. Imagine what happens, for example, if each language team (Go, Java, Python, etc.) invents their own term for "metadata", so we end up with 4 different terms for the same concept.

[aozarov]

I don't think we picked "Info" just because it is shorter than "Metadata".
In addition to being shorter (which is a plus in my mind) we favored it because:

• There is already "metadata" in the metadata/info for "User-provided metadata".
• For blob this is indeed and strictly metadata but that may not be the case for Bucket
  and for sure not the case in other services where that object (e.g. Project) is basically
  the representation of that information. Consistency in that case and between APIs of the same
  client (and therefore language) is important.
• Consistency between different languages is nice but was never a priority. We would
  always favor idiomatic style vs cross-language consistency but I don't think we put
  much efforts for cross-language consistency otherwise (/cc @jgeewax).
  e.g. GO is using ObjectHandle to represent the blob and ObjectAttrs for the blob's metadata.
  In Python the two are unified (as suggested by this issue and will solve the naming issue).

[mderka]

I am inclined towards unifying them. I agree with @ajkannan that there might be some level of confusion about the differences between the xxxInfo object and xxx itself. I feel that the unified design would be cleaner.

[ajkannan]

Closing this since the functional objects have been made subclasses of the metadata objects in all relevant modules (BigQuery, Resource Manager, and Storage).