Package com.github.ambry.router

Interface Router

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

public interface Router
extends java.io.Closeable

The router interface for Ambry that helps to interact with Ambry server.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the router and releases any resources held by the router.
default java.util.concurrent.Future<java.lang.Void>	deleteBlob(java.lang.String blobId, java.lang.String serviceId)	Requests for a blob to be deleted asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.
java.util.concurrent.Future<java.lang.Void>	deleteBlob(java.lang.String blobId, java.lang.String serviceId, Callback<java.lang.Void> callback)	Requests for a blob to be deleted asynchronously and invokes the Callback when the request completes.
default java.util.concurrent.Future<GetBlobResult>	getBlob(java.lang.String blobId, GetBlobOptions options)	Requests for blob (info, data, or both) asynchronously with user-set GetBlobOptions and returns a future that will eventually contain a GetBlobResult that can contain either the BlobInfo, the ReadableStreamChannel containing the blob data, or both.
java.util.concurrent.Future<GetBlobResult>	getBlob(java.lang.String blobId, GetBlobOptions options, Callback<GetBlobResult> callback)	Requests for the blob (info, data, or both) asynchronously and invokes the Callback when the request completes.
default java.util.concurrent.Future<java.lang.String>	putBlob(BlobProperties blobProperties, byte[] userMetadata, ReadableStreamChannel channel, PutBlobOptions options)	Requests for a new blob to be put asynchronously and returns a future that will eventually contain the BlobId of the new blob on a successful response.
java.util.concurrent.Future<java.lang.String>	putBlob(BlobProperties blobProperties, byte[] userMetadata, ReadableStreamChannel channel, PutBlobOptions options, Callback<java.lang.String> callback)	Requests for a new blob to be put asynchronously and invokes the Callback when the request completes.
default java.util.concurrent.Future<java.lang.String>	stitchBlob(BlobProperties blobProperties, byte[] userMetadata, java.util.List<ChunkInfo> chunksToStitch)	Requests for a new metadata blob to be put asynchronously and invokes the Callback when the request completes.
java.util.concurrent.Future<java.lang.String>	stitchBlob(BlobProperties blobProperties, byte[] userMetadata, java.util.List<ChunkInfo> chunksToStitch, Callback<java.lang.String> callback)	Requests for a new metadata blob to be put asynchronously and invokes the Callback when the request completes.
default java.util.concurrent.Future<java.lang.Void>	undeleteBlob(java.lang.String blobId, java.lang.String serviceId)	Requests for a blob to be undeleted asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.
java.util.concurrent.Future<java.lang.Void>	undeleteBlob(java.lang.String blobId, java.lang.String serviceId, Callback<java.lang.Void> callback)	Requests for a blob to be undeleted asynchronously and invokes the Callback when the request completes.
default java.util.concurrent.Future<java.lang.Void>	updateBlobTtl(java.lang.String blobId, java.lang.String serviceId, long expiresAtMs)	Requests that a blob's TTL be updated asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.
java.util.concurrent.Future<java.lang.Void>	updateBlobTtl(java.lang.String blobId, java.lang.String serviceId, long expiresAtMs, Callback<java.lang.Void> callback)	Requests that a blob's TTL be updated asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.

Method Detail

getBlob

java.util.concurrent.Future<GetBlobResult> getBlob(java.lang.String blobId,
                                                   GetBlobOptions options,
                                                   Callback<GetBlobResult> callback)

Requests for the blob (info, data, or both) asynchronously and invokes the Callback when the request completes.

Parameters:

blobId - The ID of the blob for which blob data is requested.

options - The options associated with the request. This cannot be null.

callback - The callback which will be invoked on the completion of the request.

Returns:

A future that would eventually contain a GetBlobResult that can contain either the BlobInfo, the ReadableStreamChannel containing the blob data, or both.

putBlob

java.util.concurrent.Future<java.lang.String> putBlob(BlobProperties blobProperties,
                                                      byte[] userMetadata,
                                                      ReadableStreamChannel channel,
                                                      PutBlobOptions options,
                                                      Callback<java.lang.String> callback)

Requests for a new blob to be put asynchronously and invokes the Callback when the request completes.

Parameters:

blobProperties - The properties of the blob. Note that the size specified in the properties is ignored. The channel is consumed fully, and the size of the blob is the number of bytes read from it.

userMetadata - Optional user metadata about the blob. This can be null.

channel - The ReadableStreamChannel that contains the content of the blob.

options - The PutBlobOptions associated with the request. This cannot be null.

callback - The Callback which will be invoked on the completion of the request .

Returns:

A future that would contain the BlobId eventually.

stitchBlob

java.util.concurrent.Future<java.lang.String> stitchBlob(BlobProperties blobProperties,
                                                         byte[] userMetadata,
                                                         java.util.List<ChunkInfo> chunksToStitch,
                                                         Callback<java.lang.String> callback)

Requests for a new metadata blob to be put asynchronously and invokes the Callback when the request completes. This metadata blob will contain references to the chunks provided as an argument. The blob ID returned by this operation can be used to fetch the chunks as if they were a single blob.

Parameters:

blobProperties - The properties of the blob. Note that the size specified in the properties is ignored. The channel is consumed fully, and the size of the blob is the number of bytes read from it.

userMetadata - Optional user metadata about the blob. This can be null.

chunksToStitch - the list of data chunks to stitch together. The router will treat the metadata in the ChunkInfo object as a source of truth, so the caller should ensure that these fields are set accurately.

callback - The Callback which will be invoked on the completion of the request .

Returns:

A future that would contain the BlobId eventually.

deleteBlob

java.util.concurrent.Future<java.lang.Void> deleteBlob(java.lang.String blobId,
                                                       java.lang.String serviceId,
                                                       Callback<java.lang.Void> callback)

Requests for a blob to be deleted asynchronously and invokes the Callback when the request completes.

Parameters:

blobId - The ID of the blob that needs to be deleted.

serviceId - The service ID of the service deleting the blob. This can be null if unknown.

callback - The Callback which will be invoked on the completion of a request.

Returns:

A future that would contain information about whether the deletion succeeded or not, eventually.

updateBlobTtl

java.util.concurrent.Future<java.lang.Void> updateBlobTtl(java.lang.String blobId,
                                                          java.lang.String serviceId,
                                                          long expiresAtMs,
                                                          Callback<java.lang.Void> callback)

Requests that a blob's TTL be updated asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.

Parameters:

blobId - The ID of the blob that needs its TTL updated.

serviceId - The service ID of the service updating the blob. This can be null if unknown.

expiresAtMs - The new expiry time (in ms) of the blob. Using Utils.Infinite_Time makes the blob permanent

callback - The Callback which will be invoked on the completion of a request.

Returns:

A future that would contain information about whether the update succeeded or not, eventually.

undeleteBlob

java.util.concurrent.Future<java.lang.Void> undeleteBlob(java.lang.String blobId,
                                                         java.lang.String serviceId,
                                                         Callback<java.lang.Void> callback)

Requests for a blob to be undeleted asynchronously and invokes the Callback when the request completes.

Parameters:

blobId - The ID of the blob that needs to be undeleted.

serviceId - The service ID of the service undeleting the blob. This can be null if unknown.

callback - The Callback which will be invoked on the completion of a request.

Returns:

A future that would contain information about whether the undelete succeeded or not, eventually.

close

void close()
    throws java.io.IOException

Closes the router and releases any resources held by the router. If the router is already closed, then this method has no effect.

After a router is closed, any further attempt to invoke Router operations will cause a RouterException with error code RouterErrorCode.RouterClosed to be returned as part of the Future and Callback if any.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException - if an I/O error occurs.

getBlob

default java.util.concurrent.Future<GetBlobResult> getBlob(java.lang.String blobId,
                                                           GetBlobOptions options)

Requests for blob (info, data, or both) asynchronously with user-set GetBlobOptions and returns a future that will eventually contain a GetBlobResult that can contain either the BlobInfo, the ReadableStreamChannel containing the blob data, or both.

Parameters:

blobId - The ID of the blob for which blob data is requested.

options - The options associated with the request.

Returns:

A future that would eventually contain a GetBlobResult that can contain either the BlobInfo, the ReadableStreamChannel containing the blob data, or both.

stitchBlob

default java.util.concurrent.Future<java.lang.String> stitchBlob(BlobProperties blobProperties,
                                                                 byte[] userMetadata,
                                                                 java.util.List<ChunkInfo> chunksToStitch)

Requests for a new metadata blob to be put asynchronously and invokes the Callback when the request completes. This metadata blob will contain references to the chunks provided as an argument. The blob ID returned by this operation can be used to fetch the chunks as if they were a single blob.

Parameters:

blobProperties - The properties of the blob. Note that the size specified in the properties is ignored. The channel is consumed fully, and the size of the blob is the number of bytes read from it.

userMetadata - Optional user metadata about the blob. This can be null.

chunksToStitch - the list of data chunks to stitch together. The router will treat the metadata in the ChunkInfo object as a source of truth, so the caller should ensure that these fields are set accurately.

Returns:

A future that would contain the BlobId eventually.

putBlob

default java.util.concurrent.Future<java.lang.String> putBlob(BlobProperties blobProperties,
                                                              byte[] userMetadata,
                                                              ReadableStreamChannel channel,
                                                              PutBlobOptions options)

Requests for a new blob to be put asynchronously and returns a future that will eventually contain the BlobId of the new blob on a successful response.

Parameters:

blobProperties - The properties of the blob. Note that the size specified in the properties is ignored. The channel is consumed fully, and the size of the blob is the number of bytes read from it.

userMetadata - Optional user metadata about the blob. This can be null.

channel - The ReadableStreamChannel that contains the content of the blob.

options - The PutBlobOptions associated with the request. This cannot be null.

Returns:

A future that would contain the BlobId eventually.

deleteBlob

default java.util.concurrent.Future<java.lang.Void> deleteBlob(java.lang.String blobId,
                                                               java.lang.String serviceId)

Requests for a blob to be deleted asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.

Parameters:

blobId - The ID of the blob that needs to be deleted.

serviceId - The service ID of the service deleting the blob. This can be null if unknown.

Returns:

A future that would contain information about whether the deletion succeeded or not, eventually.

updateBlobTtl

default java.util.concurrent.Future<java.lang.Void> updateBlobTtl(java.lang.String blobId,
                                                                  java.lang.String serviceId,
                                                                  long expiresAtMs)

Requests that a blob's TTL be updated asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.

Parameters:

blobId - The ID of the blob that needs its TTL updated.

serviceId - The service ID of the service updating the blob. This can be null if unknown.

expiresAtMs - The new expiry time (in ms) of the blob. Using Utils.Infinite_Time makes the blob permanent

Returns:

A future that would contain information about whether the update succeeded or not, eventually.

undeleteBlob

default java.util.concurrent.Future<java.lang.Void> undeleteBlob(java.lang.String blobId,
                                                                 java.lang.String serviceId)

Requests for a blob to be undeleted asynchronously and returns a future that will eventually contain information about whether the request succeeded or not.

Parameters:

blobId - The ID of the blob that needs to be undeleted.

serviceId - The service ID of the service undeleting the blob. This can be null if unknown.

Returns:

A future that would contain information about whether the undelete succeeded or not, eventually.