Clarify the semantics of the BlobContainer interface

[abeyad]

This commit clarifies the behavior that must be adhered to by any implementors of the BlobContainer interface. This is done through expanded Javadocs.

Closes #15580

[jpountz]

can you use expectThrows instead?

[jpountz]

(there seems to be a consensus around using expectThrows rather than this try/fail/catch/assert pattern for new tests)

[abeyad]

@jpountz thank you for the feedback! I made the changes, and am catching IOExceptions now

[jpountz]

Is it worth mentioning? This would be true for any Java code?

[jpountz]

Thanks for improving it. I think @rmuir should have a look to confirm it fully addresses #15580.

[tlrx]

I'm not in favour of removing the blobSize information. It can be very useful for implementations to know in advance the size of the blob to be written. For example, the impl could decide to store small blobs differently from large ones... Some clients could also use this info when uploading the blob to a remote storage service like S3/Azure/GCS. Depending of the size of the blob, it can be uploaded in 1 request and large ones could be sent in multiple multi-part requests.

Also, this is required by the upcoming #13578.

[abeyad]

@tlrx that's good to know, I didn't realize it was needed by the Google storage plugin. I'll add it back.

[abeyad]

@rmuir would you like to take a look at this PR with regards to #15580?

[rmuir]

what if there is an error? should it just return false or throw an unchecked exception?

[abeyad]

@rmuir good catch! I'm updating it to reflect that an IOException should be thrown if an error occurs while trying to ascertain the existence of the named blob.

[rmuir]

Thanks for documenting this! It is much better. I added some questions for potential followup improvements of this stuff. But the contract is now way more clear: +1

[abeyad]

@rmuir I've pushed a new commit c3c5931

Thank you for reviewing this!

[abeyad]

@rmuir I changed deleteBlob's javadocs to reflect that the contract is to throw an IOException if the blob does not exist, and this issue captures the various BlobContainer implementations that need to be fixed in order to conform: #18530

[abeyad]

@rmuir do you think any other changes are required or is the PR in good shape now? (combined with the github issues created to address the outstanding issues)

[rmuir]

sorry i missed your ping, I was +1 8 days ago for these changes! Thanks for opening followups

[abeyad]

Thanks @rmuir and @jpountz for your reviews!