add Storage.upload(Path)

[dmitry-fa]

In addition to Blob.uploadFrom() methods which require a Blob instance to be created first there should be a way to upload a resource to the storage without creating an instance of Blob:

interface Storage {
    void upload(BlobInfo blobInfo, Path path, BlobWriteOption... options);
    void upload(BlobInfo blobInfo, InputStream content, BlobWriteOption... options);
}

Implementing this feature means extending of public interface.

[dmitry-fa]

Extension the Storage interface is incompatible change. Such a minor feature as adding helper upload methods should not break compatibility. Instead of extending the main interface it's better to introduce a new class like StorageUtilities and put various helpers there.

[frankyn]

How is Storage interface change incompatible change in this case? I still think we should add the method under Storage and not create a separate helper utility.

[dmitry-fa]

Interface extension is backward incompatible change.

[frankyn]

We've been adding new methods to the interface for several features outside of this request. Could you clarify what you mean?

If we move forward with the feature added in #214 it will create a fracture in developer experience. We can try to do something else, but I'd prefer Storage.upload() over a separate helper class.

cc: @JesseLovelace @elharo @crwilcox

[dmitry-fa]

Extending interface breaks the API and requires a major version update since this API post 1.0.
Adding upload functionality is rather a small feature, it just adds a few helper methods. I don't think it deserves a major version update. The helper class will allow to add small feature like this without breaking the API.

[frankyn]

I agree that this doesn't substantiate a major version bump.
I don't agree that we should do this as a separate utility class. It is a fracture in the experience.

What is the failure that you're hitting by updating the Storage API surface?

[elharo]

You can't add a method to an interface without breaking the API.

[frankyn]

I misunderstood. damn, we have breaking the API without major version bumps for a couple of years then.

What other alternatives do we have to continue supporting requests in Storage.java? It really changes the way we execute work so I'm a bit confused.

[elharo]

There are at least 3 ways forward:

1. Use concrete classes for new functionality.
2. Add a new subinterface.
3. Increment the major version.

There's a fourth once we drop Java 7 support. Maybe some others I haven't thought of.

[frankyn]

Shared an internal document to help unblock the existing dev path for now. It will hold up other work as well that needs to be released this way.

[dmitry-fa]

@frankyn

Shared an internal document

What the document did you share?

[frankyn]

It's an internal document with Googlers right now. I'm sorting it out. I'll follow-up later today. Thanks for your patience @dmitry-fa

[frankyn]

Hi @dmitry-fa, could you send me an email at coderfrank@google.com, I'm not able to find your email.

[dmitry-fa]

To move further with this issue:

• test: update FakeStorageRpc to extend StorageRpcTestBase java-storage-nio#135 should be integrated
• java-storage-nio should be released