[jira] [Updated] (OAK-8519) [Direct Binary Access] Clearly explain causes of missing binaries for getting download URI

["Matt Ryan (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/OAK-8519?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Matt Ryan updated OAK-8519:
---------------------------
    Component/s: doc

> [Direct Binary Access] Clearly explain causes of missing binaries for getting download URI
> ------------------------------------------------------------------------------------------
>
>                 Key: OAK-8519
>                 URL: https://issues.apache.org/jira/browse/OAK-8519
>             Project: Jackrabbit Oak
>          Issue Type: Improvement
>          Components: blob-cloud, blob-cloud-azure, blob-plugins, doc
>            Reporter: Matt Ryan
>            Assignee: Matt Ryan
>            Priority: Major
>
> OAK-7998 was a good improvement for direct binary access to avoid returning a direct download URI for a binary that does not exist in cloud storage.  However, the implementation is now somewhat ambiguous and does not help the client determine what was wrong.
> There are a few cases:
>  * If direct binary download is not available (e.g. unsupported in the data store implementation or not enabled via configuration) then requesting a direct download URI for a binary returns null.
>  * If a binary is added via traditional upload (i.e. not via direct binary upload) and then a download URI is requested, it is possible that the binary is still in local cache and not in the cloud yet, and thus a direct download URI is not yet available.  Null is currently returned in this case.  (This is the use case for OAK-7998)
>  * If a binary is somehow permanently missing from cloud storage, null is returned.  This is a use case that shouldn't happen in normal operation but of course is possible.
> Returning null for each case makes it ambiguous to a client and hard to determine why the null URI was returned.
> I propose an improvement to direct download generation as follows:
>  * For the case where the direct binary download feature is not available, continue to return null as is currently being done and as is described in the documentation already.
>  * For the case where the binary does not exist, the implementation should check to see if the binary is in the data store cache.  This should be possible via the {{AbstractSharedCachingDataStore.getCache()}} method.
>  ** If the binary is in the cache throw an exception along the lines of "BinaryTemporarilyUnavailableException" indicating that the binary is not yet available for direct download but should be soon.
>  ** If not in the cache, instead throw a different exception along the lines of "BinaryNotFoundException" which is a more severe type of error.
> The exceptions can be instances of {{RepositoryException}} or subclasses of it, which would not require an API change and therefore would allow this fix to be backported to 1.10.



--
This message was sent by Atlassian JIRA
(v7.6.14#76016)