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. See Avatar image request API Documentation.

  • Method Details

    • fromEmail

      public static GravatarAvatarRequest fromEmail(String email)
      Constructs and returns a new GravatarAvatarRequest.
      Parameters:
      email - the email for this Gravatar Avatar request
      Throws:
      NullPointerException - if the email is null
      IllegalArgumentException - if the 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 Gravatar Avatar request
      Throws:
      NullPointerException - if the hash is null
      IllegalArgumentException - if the 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 if this method is invoked.
      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.
      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 imageLength)
      Sets the length of the image this request should return.
      Parameters:
      imageLength - the length of the image this request should return
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the provided image length is not in the range IMAGE_SIZE_RANGE

    • getSize

      public int getSize()
      Returns the length of the image this request should return.
      Returns:
      the length 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 and returns a BufferedImage using the URL constructed from the current state of this.
      Returns:
      a BufferedImage representing an Avatar
      Throws:
      GravatarJavaClientException - if an exception occurs reading from the URL

    • getImageIcon

      public ImageIcon getImageIcon()
      Reads and returns an ImageIcon using the URL constructed from the current state of this.
      Returns:
      an ImageIcon representing an Avatar
      Throws:
      GravatarJavaClientException - if an exception occurs reading from the URL

    • saveAsPng

      @CheckReturnValue public boolean saveAsPng(File saveTo)
      Saves an 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 an 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 an 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 a jpg yet named "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.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this

    • hashCode

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

    • equals

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