com.github.ambry.rest

Class RestUtils

java.lang.Object

com.github.ambry.rest.RestUtils

public class RestUtils
extends java.lang.Object

Common utility functions that will be used across implementations of REST interfaces.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RestUtils.Headers Ambry specific HTTP headers.
static class	RestUtils.InternalKeys Ambry specific keys used internally in a RestRequest.
static class	RestUtils.MultipartPost
static class	RestUtils.SubResource Permitted sub-resources of a blob.
static class	RestUtils.TrackingHeaders

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BYTE_RANGE_UNITS
static java.lang.String	HTTP_DATE_FORMAT
static java.lang.String	JSON_CONTENT_TYPE
static java.lang.String	SIGNED_ID_PREFIX

Constructor Summary

Constructors

Constructor and Description
RestUtils()

Method Summary

Modifier and Type	Method and Description
static void	accountAndContainerNamePreconditionCheck(RestRequest restRequest) Check preconditions for request if the restRequest contains the target account and container.
static BlobProperties	buildBlobProperties(java.util.Map<java.lang.String,java.lang.Object> args) Builds BlobProperties given the arguments associated with a request.
static com.github.ambry.utils.Pair<java.lang.String,java.lang.Long>	buildContentRangeAndLength(ByteRange range, long blobSize) Build the value for the Content-Range header that corresponds to the provided range and blob size.
static GetBlobOptions	buildGetBlobOptions(java.util.Map<java.lang.String,java.lang.Object> args, RestUtils.SubResource subResource, GetOption getOption, int blobSegmentIdx) Build a GetBlobOptions object from an argument map for a certain sub-resource.
static java.util.Map<java.lang.String,java.lang.String>	buildUserMetadata(byte[] userMetadata) Gets deserialized metadata from the byte array if possible
static byte[]	buildUserMetadata(java.util.Map<java.lang.String,java.lang.Object> args) Builds user metadata given the arguments associated with a request.
static void	ensureRequiredHeadersOrThrow(RestRequest restRequest, java.util.Set<java.lang.String> requiredHeaders) Ensures the required headers are present.
static Account	getAccountFromArgs(java.util.Map<java.lang.String,java.lang.Object> args) Extract the injected Account from a map of arguments.
static boolean	getBooleanHeader(java.util.Map<java.lang.String,java.lang.Object> args, java.lang.String header, boolean required) Gets the value of a header as a boolean.
static Container	getContainerFromArgs(java.util.Map<java.lang.String,java.lang.Object> args) Extract the injected Container from a map of arguments.
static GetOption	getGetOption(RestRequest restRequest, GetOption defaultGetOption) Gets the GetOption required by the request.
static java.lang.String	getHeader(java.util.Map<java.lang.String,?> args, java.lang.String header, boolean required) Gets the value of the header header in args.
static java.lang.Long	getLongHeader(java.util.Map<java.lang.String,?> args, java.lang.String header, boolean required) Gets the value of a header as a Long
static <T extends java.lang.Number> T	getNumericalHeader(java.util.Map<java.lang.String,?> args, java.lang.String header, boolean required, java.util.function.Function<java.lang.String,T> converter) Gets the value of a header as a Number, using the provided converter function to parse the string.
static RequestPath	getRequestPath(RestRequest restRequest) Extract the RequestPath object from RestRequest arguments.
static java.lang.Long	getTimeFromDateString(java.lang.String dateString) Fetch time in ms for the dateString passed in, since epoch
static boolean	isChunkUpload(java.util.Map<java.lang.String,java.lang.Object> args) Determine if RestUtils.Headers.CHUNK_UPLOAD is set in the request args.
static boolean	isPrivate(java.util.Map<java.lang.String,java.lang.Object> args) Gets the isPrivate setting from the args.
static boolean	setUserMetadataHeaders(byte[] userMetadata, RestResponseChannel restResponseChannel) Sets the user metadata in the headers of the response.
static long	toSecondsPrecisionInMs(long ms) Reduces the precision of a time in milliseconds to seconds precision.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HTTP_DATE_FORMAT

public static final java.lang.String HTTP_DATE_FORMAT

See Also:

Constant Field Values

BYTE_RANGE_UNITS

public static final java.lang.String BYTE_RANGE_UNITS

See Also:

Constant Field Values

SIGNED_ID_PREFIX

public static final java.lang.String SIGNED_ID_PREFIX

See Also:

Constant Field Values

JSON_CONTENT_TYPE

public static final java.lang.String JSON_CONTENT_TYPE

See Also:

Constant Field Values

Constructor Detail

RestUtils

public RestUtils()

Method Detail

buildBlobProperties

public static BlobProperties buildBlobProperties(java.util.Map<java.lang.String,java.lang.Object> args)
                                          throws RestServiceException

Builds BlobProperties given the arguments associated with a request.

Parameters:

args - the arguments associated with the request. Cannot be null.

Returns:

the BlobProperties extracted from the arguments.

Throws:

RestServiceException - if required arguments aren't present or if they aren't in the format or number expected.

buildUserMetadata

public static byte[] buildUserMetadata(java.util.Map<java.lang.String,java.lang.Object> args)
                                throws RestServiceException

Builds user metadata given the arguments associated with a request.

The following binary format will be used:

  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 |         |   size    |  total   |           |          |             |            |            |            |            |
 | version | excluding |  no of   | key1 size |   key1   | value1 size |  value 1   |  key2 size |     ...    |     Crc    |
 |(2 bytes)| ver & crc | entries  | (4 bytes) |(key1 size| (4 bytes)   |(value1 size|  (4 bytes) |     ...    |  (8 bytes) |
 |         | (4 bytes) | (4 bytes)|           |   bytes) |             |   bytes)   |            |            |            |
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  version        - The version of the user metadata record

  size exluding
  ver & CRC      - The size of the user metadata content excluding the version and the CRC

  total no of
  entries        - Total number of entries in user metadata

  key1 size      - Size of 1st key

  key1           - Content of key1

  value1 size    - Size of 1st value

  value1         - Content of value1

  key2 size      - Size of 2nd key

  crc        - The crc of the user metadata record
 

Parameters:

args - the arguments associated with the request.

Returns:

the user metadata extracted from arguments.

Throws:

RestServiceException - if usermetadata arguments have null values.

buildUserMetadata

public static java.util.Map<java.lang.String,java.lang.String> buildUserMetadata(byte[] userMetadata)

Gets deserialized metadata from the byte array if possible

Parameters:

userMetadata - the byte array which has the user metadata

Returns:

the user metadata that is read from the byte array, or null if the userMetadata cannot be parsed in expected format

buildGetBlobOptions

public static GetBlobOptions buildGetBlobOptions(java.util.Map<java.lang.String,java.lang.Object> args,
                                                 RestUtils.SubResource subResource,
                                                 GetOption getOption,
                                                 int blobSegmentIdx)
                                          throws RestServiceException

Build a GetBlobOptions object from an argument map for a certain sub-resource.

Parameters:

args - the arguments associated with the request. This is typically a map of header names and query string arguments to values.

subResource - the RestUtils.SubResource for the request, or null if no sub-resource is requested.

getOption - the GetOption required.

blobSegmentIdx - index of blob segment one wishes to GET, GetBlobOptions.NO_BLOB_SEGMENT_IDX_SPECIFIED if not used

Returns:

a populated GetBlobOptions object.

Throws:

RestServiceException - if the GetBlobOptions could not be constructed.

buildContentRangeAndLength

public static com.github.ambry.utils.Pair<java.lang.String,java.lang.Long> buildContentRangeAndLength(ByteRange range,
                                                                                                      long blobSize)
                                                                                               throws RestServiceException

Build the value for the Content-Range header that corresponds to the provided range and blob size. The returned Content-Range header value will be in the following format: {a}-{b}/{c}, where {a} is the inclusive start byte offset of the returned range, {b} is the inclusive end byte offset of the returned range, and {c} is the total size of the blob in bytes. This function also generates the range length in bytes.

Parameters:

range - a ByteRange used to generate the Content-Range header.

blobSize - the total size of the associated blob in bytes.

Returns:

a Pair containing the content range header value and the content length in bytes.

Throws:

RestServiceException

getRequestPath

public static RequestPath getRequestPath(RestRequest restRequest)

Extract the RequestPath object from RestRequest arguments.

Parameters:

restRequest - the RestRequest.

Returns:

the RequestPath

getTimeFromDateString

public static java.lang.Long getTimeFromDateString(java.lang.String dateString)

Fetch time in ms for the dateString passed in, since epoch

Parameters:

dateString - the String representation of the date that needs to be parsed

Returns:

Time in ms since epoch. Note http time is kept in Seconds so last three digits will be 000. Returns null if the dateString is not in the expected format or could not be parsed

toSecondsPrecisionInMs

public static long toSecondsPrecisionInMs(long ms)

Reduces the precision of a time in milliseconds to seconds precision. Result returned is in milliseconds with last three digits 000. Useful for comparing times kept in milliseconds that get converted to seconds and back (as is done with HTTP date format).

Parameters:

ms - time that needs to be parsed

Returns:

milliseconds with seconds precision (last three digits 000).

getGetOption

public static GetOption getGetOption(RestRequest restRequest,
                                     GetOption defaultGetOption)
                              throws RestServiceException

Gets the GetOption required by the request.

Parameters:

restRequest - the representation of the request.

defaultGetOption - the GetOption to use if the restRequest doesn't have one. Can be null.

Returns:

the required GetOption. Defaults to GetOption.None.

Throws:

RestServiceException - if the RestUtils.Headers.GET_OPTION is present but not recognized.

isPrivate

public static boolean isPrivate(java.util.Map<java.lang.String,java.lang.Object> args)
                         throws RestServiceException

Gets the isPrivate setting from the args.

Parameters:

args - The args where to include the isPrivate setting.

Returns:

A boolean to indicate the value of the isPrivate flag.

Throws:

RestServiceException - if exception occurs during parsing the arg.

isChunkUpload

public static boolean isChunkUpload(java.util.Map<java.lang.String,java.lang.Object> args)
                             throws RestServiceException

Determine if RestUtils.Headers.CHUNK_UPLOAD is set in the request args.

Parameters:

args - The request arguments.

Returns:

true if RestUtils.Headers.CHUNK_UPLOAD is set.

Throws:

RestServiceException - if exception occurs during parsing the arg.

ensureRequiredHeadersOrThrow

public static void ensureRequiredHeadersOrThrow(RestRequest restRequest,
                                                java.util.Set<java.lang.String> requiredHeaders)
                                         throws RestServiceException

Ensures the required headers are present.

Parameters:

restRequest - The RestRequest to ensure header presence. Cannot be null.

requiredHeaders - A set of headers to check presence. Cannot be null.

Throws:

RestServiceException - if any of the headers is missing.

getHeader

public static java.lang.String getHeader(java.util.Map<java.lang.String,?> args,
                                         java.lang.String header,
                                         boolean required)
                                  throws RestServiceException

Gets the value of the header header in args.

Parameters:

args - a map of arguments to be used to look for header.

header - the name of the header.

required - if true, IllegalArgumentException will be thrown if header is not present in args.

Returns:

the value of header in args if it exists. If it does not exist and required is false, then returns null.

Throws:

RestServiceException - if required is true and header does not exist in args or if there is more than one value for header in args.

getLongHeader

public static java.lang.Long getLongHeader(java.util.Map<java.lang.String,?> args,
                                           java.lang.String header,
                                           boolean required)
                                    throws RestServiceException

Gets the value of a header as a Long

Parameters:

args - a map of arguments to be used to look for header.

header - the name of the header.

required - if true, RestServiceException will be thrown if header is not present in args.

Returns:

the value of header in args if it exists. If it does not exist and required is false, then returns null.

Throws:

RestServiceException - same as cases of getHeader(Map, String, boolean) and if the value cannot be converted to a Long.

getNumericalHeader

public static <T extends java.lang.Number> T getNumericalHeader(java.util.Map<java.lang.String,?> args,
                                                                java.lang.String header,
                                                                boolean required,
                                                                java.util.function.Function<java.lang.String,T> converter)
                                                         throws RestServiceException

Gets the value of a header as a Number, using the provided converter function to parse the string.

Parameters:

args - a map of arguments to be used to look for header.

header - the name of the header.

required - if true, RestServiceException will be thrown if header is not present in args.

converter - a function to convert from a String to the desired numerical type. This should throw NumberFormatException if the argument is not a valid number.

Returns:

the value of header in args if it exists. If it does not exist and required is false, then returns null.

Throws:

RestServiceException - same as cases of getHeader(Map, String, boolean) and if the value cannot be converted to a Long.

getBooleanHeader

public static boolean getBooleanHeader(java.util.Map<java.lang.String,java.lang.Object> args,
                                       java.lang.String header,
                                       boolean required)
                                throws RestServiceException

Gets the value of a header as a boolean.

Parameters:

args - a map of arguments to be used to look for header.

header - the name of the header.

required - if true, RestServiceException will be thrown if header is not present in args.

Returns:

true if the header's value is "true" (case-insensitive), or false if the header's value is "false (case-insensitive) or the header is not present and required is false.

Throws:

RestServiceException - same as cases of getHeader(Map, String, boolean) and if the value cannot be converted to a boolean.

getAccountFromArgs

public static Account getAccountFromArgs(java.util.Map<java.lang.String,java.lang.Object> args)
                                  throws RestServiceException

Extract the injected Account from a map of arguments.

Parameters:

args - a map of arguments that possibly contains the injected Account and Container.

Returns:

the Account

Throws:

RestServiceException

getContainerFromArgs

public static Container getContainerFromArgs(java.util.Map<java.lang.String,java.lang.Object> args)
                                      throws RestServiceException

Extract the injected Container from a map of arguments.

Parameters:

args - a map of arguments that possibly contains the injected Account and Container.

Returns:

a Container

Throws:

RestServiceException

accountAndContainerNamePreconditionCheck

public static void accountAndContainerNamePreconditionCheck(RestRequest restRequest)
                                                     throws RestServiceException

Check preconditions for request if the restRequest contains the target account and container.

Parameters:

restRequest - the RestRequest that contains the Account and Container details.

Throws:

RestServiceException - if preconditions check failed.

setUserMetadataHeaders

public static boolean setUserMetadataHeaders(byte[] userMetadata,
                                             RestResponseChannel restResponseChannel)
                                      throws RestServiceException

Sets the user metadata in the headers of the response.

Parameters:

userMetadata - the user metadata that needs to be sent.

restResponseChannel - the RestResponseChannel that is used for sending the response.

Returns:

true if the user metadata was successfully deserialized into headers, false if not.

Throws:

RestServiceException - if there are any problems setting the header.