Package com.github.natche.gravatarjavaclient.avatar

Class GravatarAvatarRequest

java.lang.Object
com.github.natche.gravatarjavaclient.avatar.GravatarAvatarRequest
public final class GravatarAvatarRequest extends Object
A class for building a Gravatar Avatar request, requesting the resource, and saving the resource to a File or a BufferedImage. Read the official Avatar image request API docs here.

  • Method Details

    • fromEmail

      public static GravatarAvatarRequest fromEmail(String email)
      Constructs and returns a new GravatarAvatarRequest.
      Parameters:
      email - the email for this request
      Throws:
      NullPointerException - if the provided email is null
      IllegalArgumentException - if the provided email is empty or not a valid email address

    • fromHash

      public static GravatarAvatarRequest fromHash(String hash)
      Constructs and returns a new GravatarAvatarRequest.
      Parameters:
      hash - the hash for this request
      Throws:
      NullPointerException - if the provided hash is null
      IllegalArgumentException - if the provided hash is empty

    • getHash

      public String getHash()
      Returns the hash for this request.
      Returns:
      the hash for this request

    • setDefaultImageUrl

      @CanIgnoreReturnValue public GravatarAvatarRequest setDefaultImageUrl(String defaultImageUrl)
      Sets the default image URL. Note, defaultImageType is set to null if this method is invoked.

      Conditions which must be met for the Gravatar API endpoint to return a default image:

      • The image must be publicly available (e.g. cannot be on an intranet, on a local development machine, behind HTTP Auth or some other firewall etc). Default images are passed through a security scan to avoid malicious content.
      • The image must be accessible via HTTP or HTTPS on the standard ports, 80 and 443, respectively.
      • The image must have a recognizable image extension (jpg, jpeg, gif, png, heic)
      • The image must not include a query string (if it does, it will be ignored)
      Parameters:
      defaultImageUrl - the default image URL
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided image URL is null
      IllegalArgumentException - if the provided image URL is empty or invalid

    • getDefaultImageUrl

      public String getDefaultImageUrl()
      Returns the default image URL.
      Returns:
      the default image URL

    • setUseFullUrlParameters

      @CanIgnoreReturnValue public GravatarAvatarRequest setUseFullUrlParameters(GravatarUseFullUrlParameters useFullUrlParameters)
      Sets whether this request should use full URL parameters.
      Parameters:
      useFullUrlParameters - whether this request should use full URL parameters
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided value is null

    • getUseFullUrlParameters

      public GravatarUseFullUrlParameters getUseFullUrlParameters()
      Returns whether this request will use full URL parameters.
      Returns:
      whether this request will use full URL parameters

    • setProtocol

      @CanIgnoreReturnValue public GravatarAvatarRequest setProtocol(GravatarProtocol protocol)
      Sets the protocol this request will use.
      Parameters:
      protocol - the protocol
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided protocol is null

    • getProtocol

      public GravatarProtocol getProtocol()
      Returns the protocol this request will use.
      Returns:
      the protocol this request will use

    • setDefaultImageType

      @CanIgnoreReturnValue public GravatarAvatarRequest setDefaultImageType(GravatarDefaultImageType imageType)
      Sets the default image type this request will use. Note defaultImageUrl is set to null after setting the internal state of this request to the provided type.
      Parameters:
      imageType - the default image type this request will use
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided image type is null

    • getDefaultImageType

      public GravatarDefaultImageType getDefaultImageType()
      Returns the default image type this request will use.
      Returns:
      the default image type this request will use

    • setForceDefaultImage

      @CanIgnoreReturnValue public GravatarAvatarRequest setForceDefaultImage(GravatarForceDefaultImage forceDefaultImage)
      Sets whether this request should force the default image.
      Parameters:
      forceDefaultImage - whether this request should force the default image
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided value is null

    • shouldForceDefaultImage

      public GravatarForceDefaultImage shouldForceDefaultImage()
      Returns whether this request should force the default image.
      Returns:
      whether this request should force the default image

    • setRating

      @CanIgnoreReturnValue public GravatarAvatarRequest setRating(GravatarRating rating)
      Sets the rating this request will use. If the resulting image's rating is above this rating, the default image will be used.
      Parameters:
      rating - the rating this request will use
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided rating is null

    • getRating

      public GravatarRating getRating()
      Returns the rating this request will use.
      Returns:
      the rating this request will use

    • setShouldAppendJpgSuffix

      @CanIgnoreReturnValue public GravatarAvatarRequest setShouldAppendJpgSuffix(GravatarUseJpgSuffix useJpgSuffix)
      Returns whether this request should append the jpg suffix to the hash.
      Parameters:
      useJpgSuffix - whether this request should append the jpg suffix to the hash
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided value is null

    • getShouldAppendJpgSuffix

      public GravatarUseJpgSuffix getShouldAppendJpgSuffix()
      Returns whether this request should append the jpg suffix to the hash.
      Returns:
      whether this request should append the jpg suffix to the hash

    • setSize

      @CanIgnoreReturnValue public GravatarAvatarRequest setSize(int imageSize)
      Sets the size of the image this request should return.
      Parameters:
      imageSize - the size of the image this request should return
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the provided image size is not in the range IMAGE_SIZE_RANGE

    • getSize

      public int getSize()
      Returns the size of the image this request should return.
      Returns:
      the size of the image this request should return

    • getRequestUrl

      public String getRequestUrl()
      Returns the URL for requesting the Avatar based on the current state of this.
      Returns:
      the URL for requesting the Avatar based on the current state of this

    • getBufferedImage

      public BufferedImage getBufferedImage()
      Reads from the URL constructed from the current state of this request using getRequestUrl(). The content is encoded into a new BufferedImage and returned.
      Returns:
      a new BufferedImage
      Throws:
      GravatarJavaClientException - if an exception occurs reading from the URL

    • saveAsPng

      @CheckReturnValue public boolean saveAsPng(File saveTo)
      Saves the image obtained from the URL constructed from this to the provided file as a png.
      Parameters:
      saveTo - the file to save the image to
      Returns:
      whether the save operation was successful
      Throws:
      NullPointerException - if the provided file is null
      IllegalArgumentException - if the provided file is a directory

    • saveAsJpg

      @CheckReturnValue public boolean saveAsJpg(File saveTo)
      Saves the image obtained from the URL constructed from this to the provided file as a jpg.
      Parameters:
      saveTo - the file to save the image to
      Returns:
      whether the save operation was successful
      Throws:
      NullPointerException - if the provided file is null
      IllegalArgumentException - if the provided file is a directory

    • saveTo

      @CheckReturnValue public boolean saveTo(File saveTo, String format)
      Saves the image obtained from the URL constructed from this to the provided file. Note, while the file could be named "Image.png", if "jpg" is provided as the format, the image will be of jpg format yet still named your provided name of "Image.png".
      Parameters:
      saveTo - the file to save the image to
      format - the format to use; see ImageIO.getWriterFormatNames()
      Returns:
      whether the save operation was successful
      Throws:
      NullPointerException - if any parameter is null
      IllegalArgumentException - if the provided format is empty or the provided file is a directory

    • toString

      public String toString()
      Returns a string representation of this request.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this request

    • hashCode

      public int hashCode()
      Returns a hashcode for this request.
      Overrides:
      hashCode in class Object
      Returns:
      a hashcode for this request

    • equals

      public boolean equals(Object o)
      Returns whether the provided object is equal to this request.
      Overrides:
      equals in class Object
      Parameters:
      o - the other object
      Returns:
      whether the provided object is equal to this request