Package com.github.ambry.rest

Class RestUtils

  • public class RestUtils
extends java.lang.Object
    Common utility functions that will be used across implementations of REST interfaces.

    • Constructor Summary

      Constructors 
      Constructor Description
      RestUtils()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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, boolean resolveRangeOnEmptyBlob)
      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 void setUserMetadataHeaders​(java.util.Map<java.lang.String,​java.lang.String> userMetadataMap, RestResponseChannel restResponseChannel)
      Sets the user metadata in the headers of the response.
      static java.lang.String stripSlashAndExtensionFromId​(java.lang.String blobIdWithExtension)
      Drops the leading slash and extension (if any) in the blob ID.
      static long toSecondsPrecisionInMs​(long ms)
      Reduces the precision of a time in milliseconds to seconds precision.
      static java.lang.String verifyChunkUploadSession​(java.util.Map<java.lang.String,​java.lang.String> chunkMetadata, java.lang.String expectedSession)
      Verify that the session ID in the chunk metadata matches the expected session.

      • Methods inherited from class java.lang.Object

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

    • 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

      • buildContentRangeAndLength

        public static com.github.ambry.utils.Pair<java.lang.String,​java.lang.Long> buildContentRangeAndLength​(ByteRange range,
                                                                                                            long blobSize,
                                                                                                            boolean resolveRangeOnEmptyBlob)
                                                                                                     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: bytes {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.
        resolveRangeOnEmptyBlob - true to force range resolution to succeed if the blob is empty. In other words, return bytes 1-0/0 if totalSize == 0.
        Returns:
        a Pair containing the content range header value and the content length in bytes.
        Throws:
        RestServiceException

      • 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).

      • 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.

      • 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.

      • 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)
        Sets the user metadata in the headers of the response.
        Parameters:
        userMetadata - byte array containing 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.

      • setUserMetadataHeaders

        public static void setUserMetadataHeaders​(java.util.Map<java.lang.String,​java.lang.String> userMetadataMap,
                                          RestResponseChannel restResponseChannel)
        Sets the user metadata in the headers of the response.
        Parameters:
        userMetadataMap - map of user metadata that needs to be sent.
        restResponseChannel - the RestResponseChannel that is used for sending the response.
        Throws:
        RestServiceException - if there are any problems setting the header.

      • verifyChunkUploadSession

        public static java.lang.String verifyChunkUploadSession​(java.util.Map<java.lang.String,​java.lang.String> chunkMetadata,
                                                        java.lang.String expectedSession)
                                                 throws RestServiceException
        Verify that the session ID in the chunk metadata matches the expected session.
        Parameters:
        chunkMetadata - the metadata map parsed from a signed chunk ID.
        expectedSession - the session that the chunk should match. This can be null for the first chunk (where any session ID is valid).
        Returns:
        this chunk's session ID
        Throws:
        RestServiceException - if the chunk has a null session ID or it does not match the expected value.

      • stripSlashAndExtensionFromId

        public static java.lang.String stripSlashAndExtensionFromId​(java.lang.String blobIdWithExtension)
        Drops the leading slash and extension (if any) in the blob ID.
        Parameters:
        blobIdWithExtension - the blob ID possibly with an extension.
        Returns:
        blobIdWithExtension without an extension if there was one.