diff --git a/src/main/java/com/sendgrid/ASM.java b/src/main/java/com/sendgrid/ASM.java index 74ba451c..529a8620 100644 --- a/src/main/java/com/sendgrid/ASM.java +++ b/src/main/java/com/sendgrid/ASM.java @@ -7,7 +7,8 @@ import java.util.Arrays; /** - * An object allowing you to specify how to handle unsubscribes. + * A JSON-serializable model, describing how unsubscribes should + * be handled. */ @JsonInclude(Include.NON_DEFAULT) public class ASM { @@ -19,7 +20,8 @@ public class ASM { private int[] groupsToDisplay; /** - * Get the group ID. + * Gets the group ID. + * * @return the group ID. */ @JsonProperty("group_id") @@ -28,9 +30,10 @@ public int getGroupId() { } /** - * Set the group ID. + * Sets the group ID. + * * @param groupId the group ID. - * @return this object. + * @return {@code this} for chaining. */ public ASM groupId(int groupId) { this.groupId = groupId; @@ -38,7 +41,8 @@ public ASM groupId(int groupId) { } /** - * Get the groups to display. + * Gets the groups to display. + * * @return the groups to display. */ @JsonProperty("groups_to_display") @@ -47,9 +51,10 @@ public int[] getGroupsToDisplay() { } /** - * Set the groups to display. + * Sets the groups to display. + * * @param groupsToDisplay the groups to display. - * @return this object. + * @return {@code this} for chaining. */ public ASM groupsToDisplay(int[] groupsToDisplay) { this.groupsToDisplay = Arrays.copyOf(groupsToDisplay, groupsToDisplay.length); diff --git a/src/main/java/com/sendgrid/Attachment.java b/src/main/java/com/sendgrid/Attachment.java index c122be30..1df4f626 100644 --- a/src/main/java/com/sendgrid/Attachment.java +++ b/src/main/java/com/sendgrid/Attachment.java @@ -9,7 +9,7 @@ import java.io.*; /** - * An attachment object. + * A JSON-serializable model of an email attachment. */ @JsonInclude(Include.NON_DEFAULT) public class Attachment { @@ -28,15 +28,16 @@ public class Attachment { /** * The attachment content ID. This is used when the - * disposition is set to “inline” and the attachment + * disposition is set to {@code "inline"} and the attachment * is an image, allowing the file to be displayed within - * the body of your email. + * the body of your email. */ @JsonProperty("content_id") private String contentId; /** - * Get the attachment's content. + * Gets the attachment content. + * * @return the content. */ @JsonProperty("content") @@ -45,9 +46,10 @@ public String getContent() { } /** - * Set the attachment's content. + * Sets the attachment content. + * * @param content the content. - * @return this object. + * @return {@code this} for chaining. */ public Attachment content(String content) { this.content = content; @@ -55,8 +57,9 @@ public Attachment content(String content) { } /** - * Get the mime type of the content you are attaching. For example, - * “text/plain” or “text/html”. + * Gets the mime type of the content you are attaching. For example, + * {@link ContentType#TEXT_PLAIN} or {@link ContentType#TEXT_HTML}. + * * @return the mime type. */ @JsonProperty("type") @@ -65,9 +68,10 @@ public String getType() { } /** - * Set the mime type of the content. + * Sets the mime type of the content. + * * @param type the mime type. - * @return this object. + * @return {@code this} for chaining. */ public Attachment type(String type) { this.type = type; @@ -75,7 +79,8 @@ public Attachment type(String type) { } /** - * Get the filename for this attachment. + * Gets the filename for this attachment. + * * @return the file name. */ @JsonProperty("filename") @@ -84,9 +89,10 @@ public String getFilename() { } /** - * Set the filename for this attachment. + * Sets the filename for this attachment. + * * @param filename the filename. - * @return this object. + * @return {@code this} for chaining. */ public Attachment filename(String filename) { this.filename = filename; @@ -94,13 +100,14 @@ public Attachment filename(String filename) { } /** - * Get the content-disposition of the attachment specifying + * Gets the content-disposition of the attachment specifying * how you would like the attachment to be displayed. - * For example, “inline” results in the attached file + * For example, {@code "inline"} results in the attached file * being displayed automatically within the message - * while “attachment” results in the attached file + * while {@code “attachment”} results in the attached file * requiring some action to be taken before it is * displayed (e.g. opening or downloading the file). + * * @return the disposition. */ @JsonProperty("disposition") @@ -109,9 +116,10 @@ public String getDisposition() { } /** - * Set the content-disposition of the attachment. + * Sets the content-disposition of the attachment. + * * @param disposition the disposition. - * @return this object. + * @return {@code this} for chaining. */ public Attachment disposition(String disposition) { this.disposition = disposition; @@ -119,10 +127,11 @@ public Attachment disposition(String disposition) { } /** - * Get the attachment content ID. This is used when the - * disposition is set to “inline” and the attachment + * Gets the attachment content ID. This is used when the + * disposition is set to {@code "inline"} and the attachment * is an image, allowing the file to be displayed within - * the body of your email. + * the body of your email. + * * @return the content ID. */ @JsonProperty("content_id") @@ -131,9 +140,10 @@ public String getContentId() { } /** - * Set the content ID. + * Sets the content ID. + * * @param contentId the content ID. - * @return this object. + * @return {@code this} for chaining. */ public Attachment contentId(String contentId) { this.contentId = contentId; @@ -141,7 +151,7 @@ public Attachment contentId(String contentId) { } /** - * A helper object to construct usable attachment. + * A builder for creating {@link Attachment}s. */ @JsonIgnoreType public static class Builder { @@ -155,7 +165,8 @@ public static class Builder { private String contentId; /** - * Construct a new attachment builder. + * Creates a new builder, for creating an {@link Attachment}. + * * @param fileName the filename to include. * @param content an input stream for the content. * @throws IllegalArgumentException in case either the fileName or the content is null. @@ -174,7 +185,8 @@ public Builder(String fileName, InputStream content) { } /** - * Construct a new attachment builder. + * Creates a new builder, for creating an {@link Attachment}. + * * @param fileName the filename to include. * @param content an input string for the content. * @throws IllegalArgumentException in case either the fileName or the content is null. @@ -207,8 +219,10 @@ private String encodeToBase64(InputStream content) { } /** - * Set the type of this attachment builder. + * Sets the type of this attachment builder. + * * @param type the attachment type. + * @return {@code this} for chaining. */ public Builder withType(String type) { this.type = type; @@ -216,8 +230,10 @@ public Builder withType(String type) { } /** - * Set the disposition of this attachment builder. + * Sets the disposition of this attachment builder. + * * @param disposition the disposition. + * @return {@code this} for chaining. */ public Builder withDisposition(String disposition) { this.disposition = disposition; @@ -225,8 +241,10 @@ public Builder withDisposition(String disposition) { } /** - * Set the content ID of this attachment builder. + * Sets the content ID of this attachment builder. + * * @param contentId the content ID. + * @return {@code this} for chaining. */ public Builder withContentId(String contentId) { this.contentId = contentId; @@ -234,7 +252,9 @@ public Builder withContentId(String contentId) { } /** - * Construct the attachment object. + * Creates the attachment model, from the specified arguments. + * + * @return the constructed attachment model. */ public Attachment build() { Attachment attachment = new Attachment() diff --git a/src/main/java/com/sendgrid/BCCSettings.java b/src/main/java/com/sendgrid/BCCSettings.java index 0d4e7804..15754b60 100644 --- a/src/main/java/com/sendgrid/BCCSettings.java +++ b/src/main/java/com/sendgrid/BCCSettings.java @@ -5,9 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * This object allows you to have a blind carbon copy - * automatically sent to the specified email address - * for every email that is sent. + * A JSON-serializable model of the blind carbon copy (BCC) + * settings. This allows for automatic copies of every + * email sent to be made to the specified email address. */ @JsonInclude(Include.NON_DEFAULT) public class BCCSettings { @@ -19,8 +19,10 @@ public class BCCSettings { private String email; /** - * Determines if this setting is enabled. - * @return true if BCC is enabled, false otherwise. + * Gets whether BCC has been enabled. + * + * @return {@code true} if BCC has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -28,9 +30,11 @@ public boolean getEnable() { } /** - * Set whether or not BCC is enabled. - * @param enable true if BCC is enabled, false otherwise. - * @return this object. + * Sets whether BCC has been enabled. + * + * @param enable {@code true} if BCC has been enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public BCCSettings enable(boolean enable) { this.enable = enable; @@ -38,8 +42,9 @@ public BCCSettings enable(boolean enable) { } /** - * Get the email address that you would like to receive the BCC. - * @return the address. + * Gets the email address that will receive the copies. + * + * @return the email address. */ @JsonProperty("email") public String getEmail() { @@ -47,9 +52,10 @@ public String getEmail() { } /** - * Set the email address that you would like to receive the BCC. - * @param email the address. - * @return this object. + * Sets the email address that will receive the copies. + * + * @param email the email address. + * @return {@code this} for chaining. */ public BCCSettings email(String email) { this.email = email; diff --git a/src/main/java/com/sendgrid/Campaign.java b/src/main/java/com/sendgrid/Campaign.java index ab93e422..25486717 100644 --- a/src/main/java/com/sendgrid/Campaign.java +++ b/src/main/java/com/sendgrid/Campaign.java @@ -5,23 +5,26 @@ import java.util.ArrayList; /** - * A class allowing multiple emails to be sent simultaneously. + * A utility for conducting a campaign, allowing for + * multiple emails to be sent simultaneously. */ public class Campaign { private final List mail = new ArrayList<>(); /** - * Get the mail objcts in this campaign. - * @return the list of mail objects. + * Gets the emails of which should be sent. + * + * @return the list of mail models. */ public List getMail() { return this.mail; } /** - * Add a mail object to this campaign. - * @param mail a mail to add to the campaign. - * @return this campaign. + * Adds an email to this campaign. + * + * @param mail a mail model + * @return {@code this} for chaining. */ public Campaign mail(Mail mail) { this.mail.add(mail); @@ -29,12 +32,13 @@ public Campaign mail(Mail mail) { } /** - * Send all the email in this campaign. - * @param sg a Sendgrid object. - * @return the list of responses from sending the mail. - * @throws IOException in the event of a network error. Note that - * if any messages throws an error, the remaining members of the - * campaign will not be sent. + * Send all the emails in this campaign. + * + * @param sg the SendGrid wrapper. + * @return the list of responses, having sent the emails. + * @throws IOException in the event of a network error. Note that if + * any messages throws an error, the remaining members + * of the campaign will not be sent. */ public List send(SendGrid sg) throws IOException { List ret = new ArrayList<>(); diff --git a/src/main/java/com/sendgrid/ClickTrackingSettings.java b/src/main/java/com/sendgrid/ClickTrackingSettings.java index 2a4b147e..3d36c159 100644 --- a/src/main/java/com/sendgrid/ClickTrackingSettings.java +++ b/src/main/java/com/sendgrid/ClickTrackingSettings.java @@ -5,8 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * Settings to determine how you would like to track the - * metrics of how your recipients interact with your email. + * A JSON-serializable model of the click tracking settings. + * This allows for tracking a variety of the interactions a + * recipient may make with your email. */ @JsonInclude(Include.NON_DEFAULT) public class ClickTrackingSettings { @@ -18,8 +19,10 @@ public class ClickTrackingSettings { private boolean enableText; /** - * Determines if this setting is enabled. - * @return true if click tracking is enabled, false otherwise. + * Gets whether click tracking has been enabled. + * + * @return {@code true} if click tracking has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -27,9 +30,11 @@ public boolean getEnable() { } /** - * Set if this setting is enabled. - * @param enable true if click tracking is enabled, false otherwise. - * @return this object. + * Sets whether click tracking has been enabled. + * + * @param enable {@code true} if click tracking has been enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public ClickTrackingSettings enable(boolean enable) { this.enable = enable; @@ -37,9 +42,10 @@ public ClickTrackingSettings enable(boolean enable) { } /** - * Get the enabled text. This indicates if this + * Gets the enabled text. This indicates if this * setting should be included in the text/plain * portion of your email. + * * @return the enable text. */ @JsonProperty("enable_text") @@ -48,9 +54,10 @@ public boolean getEnableText() { } /** - * Set the enalbed text. + * Sets the enabled text. + * * @param enableText the enable text. - * @return this object. + * @return {@code this} for chaining. */ public ClickTrackingSettings enableText(boolean enableText) { this.enableText = enableText; diff --git a/src/main/java/com/sendgrid/Content.java b/src/main/java/com/sendgrid/Content.java index 09a0682a..83c10a42 100644 --- a/src/main/java/com/sendgrid/Content.java +++ b/src/main/java/com/sendgrid/Content.java @@ -5,7 +5,14 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * An object in which you may specify the content of your email. + * A JSON-serializable representation of the content of an email. + *

+ * This class has the capabilities to be chained, like so: + * + * final Content content = new Content() + * .type(ContentType.TEXT_PLAIN) + * .value("Hello, World!"); + * */ @JsonInclude(Include.NON_DEFAULT) public class Content { @@ -17,16 +24,17 @@ public class Content { private String value; /** - * Construct an empty content object. + * Creates a new content wrapper, with no content. */ public Content() { - } /** - * Get the mime type of the content you are including - * in your email. For example, “text/plain” or “text/html”. + * Gets the mime type of the content of the email. For example, + * {@code text/plain} or {@code text/html}. + * * @return the mime type. + * @see ContentType for a psuedo-enum of potential content types */ @JsonProperty("type") public String getType() { @@ -34,10 +42,12 @@ public String getType() { } /** - * Set the mime type of the content you are including - * in your email. For example, “text/plain” or “text/html”. + * Sets the mime type of the content of the email. For example, + * {@code text/plain} or {@code text/html}. + * * @param type the mime type. - * @return this object. + * @return {@code this} for chaining. + * @see ContentType for a psuedo-enum of potential content types */ public Content type(String type) { this.type = type; @@ -45,9 +55,10 @@ public Content type(String type) { } /** - * Get the actual content of the specified mime type - * that you are including in your email. - * @return the value. + * Gets the content of the email. The type of the content should + * match the specified mime type. + * + * @return the content. */ @JsonProperty("value") public String getValue() { @@ -55,10 +66,11 @@ public String getValue() { } /** - * Set the actual content of the specified mime type - * that you are including in your email. - * @param value the value. - * @return this object. + * Sets the content of the email. The type of the content should + * match the specified mime type. + * + * @param value the content. + * @return {@code this} for chaining. */ public Content value(String value) { this.value = value; diff --git a/src/main/java/com/sendgrid/ContentType.java b/src/main/java/com/sendgrid/ContentType.java index 2ccbdeac..f5f43041 100644 --- a/src/main/java/com/sendgrid/ContentType.java +++ b/src/main/java/com/sendgrid/ContentType.java @@ -1,7 +1,8 @@ package com.sendgrid; /** - * Content type enumeration. + * Pseudo-enumeration of Content-Types. + * * @author Marcos Barbero */ public class ContentType { diff --git a/src/main/java/com/sendgrid/Email.java b/src/main/java/com/sendgrid/Email.java index edc41893..c5096d73 100644 --- a/src/main/java/com/sendgrid/Email.java +++ b/src/main/java/com/sendgrid/Email.java @@ -5,7 +5,14 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * An email address represented as an address name pair. + * A JSON-serializable representation of an email address pair. + *

+ * This class has the capabilities to be chained, like so: + * + * final Email email = new Email() + * .name("John Doe") + * .email("john@doe.com"); + * */ @JsonInclude(Include.NON_DEFAULT) public class Email { @@ -17,15 +24,16 @@ public class Email { private String email; /** - * Construct an empty email. + * Creates a new email wrapper, with no name or email. */ public Email() { - } /** - * Get the name. - * @return the name. + * Gets the human-readable name of the email owner - for + * example: John Doe. + * + * @return the human-readable name. */ @JsonProperty("name") public String getName() { @@ -33,9 +41,10 @@ public String getName() { } /** - * Set the name. - * @param name the name. - * @return this object. + * Sets the human-readable name of the email owner. + * + * @param name the human-readable name. + * @return {@code this} for chaining. */ public Email name(String name) { this.name = name; @@ -43,7 +52,8 @@ public Email name(String name) { } /** - * Get the email address. + * Gets the email address - for example: john@doe.com. + * * @return the email address. */ @JsonProperty("email") @@ -52,9 +62,10 @@ public String getEmail() { } /** - * Set the email address. + * Sets the email address. + * * @param email the email address. - * @return this object. + * @return {@code this} for chaining. */ public Email email(String email) { this.email = email; diff --git a/src/main/java/com/sendgrid/FooterSettings.java b/src/main/java/com/sendgrid/FooterSettings.java index 9bc2de68..bac455c1 100644 --- a/src/main/java/com/sendgrid/FooterSettings.java +++ b/src/main/java/com/sendgrid/FooterSettings.java @@ -5,8 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * An object representing the default footer - * that you would like included on every email. + * A JSON-serializable model of the footer settings. + * This allows for a default footer to be included + * on every email sent. */ @JsonInclude(Include.NON_DEFAULT) public class FooterSettings { @@ -21,8 +22,10 @@ public class FooterSettings { private String html; /** - * Get whether or not the footer is enabled. - * @return true if the footer is enabled, false otherwise. + * Gets whether the footer has been enabled. + * + * @return {@code true} if the footer has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -30,9 +33,11 @@ public boolean getEnable() { } /** - * Set whether or not the footer is enabled. - * @param enable true if the footer is enabled, false otherwise. - * @return this object. + * Sets whether the footer has been enabled. + * + * @param enable {@code true} if the footer has been enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public FooterSettings enable(boolean enable) { this.enable = enable; @@ -40,7 +45,8 @@ public FooterSettings enable(boolean enable) { } /** - * Get the plain text content of the footer. + * Gets the plain text content of the footer. + * * @return the footer plain text. */ @JsonProperty("text") @@ -49,9 +55,10 @@ public String getText() { } /** - * Set the plain text content of the footer. + * Sets the plain text content of the footer. + * * @param text the footer plain text. - * @return this object. + * @return {@code this} for chaining. */ public FooterSettings text(String text) { this.text = text; @@ -59,7 +66,8 @@ public FooterSettings text(String text) { } /** - * Get the HTML content of the footer. + * Gets the HTML content of the footer. + * * @return the footer HTML. */ @JsonProperty("html") @@ -68,9 +76,10 @@ public String getHtml() { } /** - * Set the HTML content of the footer. + * Sets the HTML content of the footer. + * * @param html the footer HTML. - * @return this object. + * @return {@code this} for chaining. */ public FooterSettings html(String html) { this.html = html; diff --git a/src/main/java/com/sendgrid/GoogleAnalyticsSettings.java b/src/main/java/com/sendgrid/GoogleAnalyticsSettings.java index 31eb4a43..c6a74001 100644 --- a/src/main/java/com/sendgrid/GoogleAnalyticsSettings.java +++ b/src/main/java/com/sendgrid/GoogleAnalyticsSettings.java @@ -5,7 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * An object configuring the tracking provided by Google Analytics. + * A JSON-serializable model of the Google Analytics settings. + * This allows for tracking provided by Google, to be used in + * emails. */ @JsonInclude(Include.NON_DEFAULT) public class GoogleAnalyticsSettings { @@ -29,8 +31,10 @@ public class GoogleAnalyticsSettings { private String campaignMedium; /** - * Get whether or not this setting is enabled. - * @return true if enabled, false otherwise. + * Gets whether Google Analytics has been enabled. + * + * @return {@code true} if Google Analytics has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -38,9 +42,11 @@ public boolean getEnable() { } /** - * Set whether or not this setting is enabled. - * @param enable true if enabled, false otherwise. - * @return this object. + * Sets whether Google Analytics has been enabled. + * + * @param enable {@code true} if Google Analytics has been enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public GoogleAnalyticsSettings enable(boolean enable) { this.enable = enable; @@ -48,8 +54,9 @@ public GoogleAnalyticsSettings enable(boolean enable) { } /** - * Get the name of the referrer source. - * (e.g. Google, SomeDomain.com, or Marketing Email) + * Get the name of the referrer source - for example: {@code Google}, + * {@code SomeDomain.com}, or {@code Marketing Email}. + * * @return the referrer source. */ @JsonProperty("utm_source") @@ -58,9 +65,10 @@ public String getCampaignSource() { } /** - * Set the name of the referrer source. + * Set the name of the referrer source. + * * @param campaignSource the referrer source. - * @return this object. + * @return {@code this} for chaining. */ public GoogleAnalyticsSettings campaignSource(String campaignSource) { this.campaignSource = campaignSource; @@ -69,6 +77,7 @@ public GoogleAnalyticsSettings campaignSource(String campaignSource) { /** * Get the term used to identify any paid keywords. + * * @return the term. */ @JsonProperty("utm_term") @@ -78,8 +87,9 @@ public String getCampaignTerm() { /** * Set the term used to identify any paid keywords. + * * @param campaignTerm the term. - * @return this object. + * @return {@code this} for chaining. */ public GoogleAnalyticsSettings campaignTerm(String campaignTerm) { this.campaignTerm = campaignTerm; @@ -87,8 +97,9 @@ public GoogleAnalyticsSettings campaignTerm(String campaignTerm) { } /** - * Get the content Used to differentiate your campaign + * Get the content used to differentiate your campaign * from advertisements. + * * @return the content. */ @JsonProperty("utm_content") @@ -97,10 +108,11 @@ public String getCampaignContent() { } /** - * Set the content Used to differentiate your campaign + * Set the content used to differentiate your campaign * from advertisements. + * * @param campaignContent the content. - * @return this object. + * @return {@code this} for chaining. */ public GoogleAnalyticsSettings campaignContent(String campaignContent) { this.campaignContent = campaignContent; @@ -109,6 +121,7 @@ public GoogleAnalyticsSettings campaignContent(String campaignContent) { /** * Get the name of the campaign. + * * @return the name. */ @JsonProperty("utm_campaign") @@ -118,8 +131,9 @@ public String getCampaignName() { /** * Set the name of the campaign. + * * @param campaignName the name. - * @return this object. + * @return {@code this} for chaining. */ public GoogleAnalyticsSettings campaignName(String campaignName) { this.campaignName = campaignName; @@ -127,7 +141,8 @@ public GoogleAnalyticsSettings campaignName(String campaignName) { } /** - * Get the name of the marketing medium. (e.g. Email) + * Get the name of the marketing medium - for example, {@code Email}. + * * @return the medium name. */ @JsonProperty("utm_medium") @@ -136,9 +151,10 @@ public String getCampaignMedium() { } /** - * Set the name of the marketing medium. (e.g. Email) + * Set the name of the marketing medium - for example, {@code Email}. + * * @param campaignMedium the medium name. - * @return this object. + * @return {@code this} for chaining. */ public GoogleAnalyticsSettings campaignMedium(String campaignMedium) { this.campaignMedium = campaignMedium; diff --git a/src/main/java/com/sendgrid/Mail.java b/src/main/java/com/sendgrid/Mail.java index fd83874d..022ffde8 100644 --- a/src/main/java/com/sendgrid/Mail.java +++ b/src/main/java/com/sendgrid/Mail.java @@ -15,8 +15,10 @@ import java.util.Map; /** - * Class Mail builds an object that sends an email through SendGrid. - * Note that this object is not thread safe. + * A JSON-serializable model of an email, to be sent through SendGrid's + * API. + *

+ * It should be noted that this class is not thread safe! */ @JsonInclude(Include.NON_DEFAULT) public class Mail { @@ -77,14 +79,16 @@ public class Mail { SORTED_MAPPER.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS, true); } - /** Construct a new Mail object. */ + /** + * Creates a new, blank, mail model. + */ public Mail() { - } /** - * Get the email's from address. - * @return the email's from address. + * Gets the email address pair of email sender. + * + * @return the sender's email address. */ @JsonProperty("from") public Email getFrom() { @@ -92,9 +96,10 @@ public Email getFrom() { } /** - * Set the email's from address. - * @param from the email's from address. - * @return this object. + * Sets the email address pair of email sender. + * + * @param from the sender's email address. + * @return {@code this} for chaining. */ public Mail from(Email from) { this.from = from; @@ -102,8 +107,12 @@ public Mail from(Email from) { } /** - * Get the email's to address list. - * @return all the to addresses. + * Gets a {@link List} view of all the email address pairs which + * should receive the email, in short - it is a view of all the + * recipients whether their name is present or otherwise. + * + * @return The recipients. + * @see Personalization#getTos() */ @JsonIgnore public List getTos() { @@ -118,14 +127,15 @@ public List getTos() { } /** - * Add a to address. This is a convenience method for adding - * an address to the a personalization object. To addresses - * are located in the Personalization object. This method adds - * the address to the first personalization, creating it if - * necessary. If you would like to add the address to a different - * personalization object, please do so directly. + * Adds a recipient to the first {@link Personalization}, creating + * one if it doesn't exist. + *

+ * If this is not the desired effect, use the + * {@link Personalization} model directly! + * * @param to the to address - * @return this object. + * @return {@code this} for chaining. + * @see Personalization#to(Email) */ public Mail to(Email to) { Personalization p; @@ -146,7 +156,8 @@ public Mail to(Email to) { } /** - * Get the email's subject line. + * Gets the email's subject line. + * * @return the email's subject line. */ @JsonProperty("subject") @@ -155,11 +166,12 @@ public String getSubject() { } /** - * Set the email's subject line. This is the global, or + * Sets the email's subject line. This is the global, or * “message level”, subject of your email. This may - * be overridden by personalizations[x].subject. + * be overridden by personalizations[x].subject. + * * @param subject the email's subject line. - * @return this object. + * @return {@code this} for chaining. */ public Mail subject(String subject) { this.subject = subject; @@ -167,7 +179,8 @@ public Mail subject(String subject) { } /** - * Get the email's unsubscribe handling object (ASM). + * Gets the email's unsubscribe handling object (ASM). + * * @return the email's ASM. */ @JsonProperty("asm") @@ -176,9 +189,10 @@ public ASM getASM() { } /** - * Set the email's unsubscribe handling object (ASM). + * Sets the email's unsubscribe handling object (ASM). + * * @param asm the email's ASM. - * @return this object. + * @return {@code this} for chaining. */ public Mail asm(ASM asm) { this.asm = asm; @@ -186,8 +200,9 @@ public Mail asm(ASM asm) { } /** - * Get the email's personalizations. Content added to the returned + * Gets the email's personalizations. Content added to the returned * list will be included when sent. + * * @return the email's personalizations. */ @JsonProperty("personalizations") @@ -196,12 +211,13 @@ public List getPersonalization() { } /** - * Add a personalization to the email. Each object within + * Adds a personalization to the email. Each object within * personalizations can be thought of as an envelope * - it defines who should receive an individual message - * and how that message should be handled. + * and how that message should be handled. + * * @param personalization a personalization. - * @return this object. + * @return {@code this} for chaining. */ public Mail personalization(Personalization personalization) { if (this.personalization == null) { @@ -214,8 +230,9 @@ public Mail personalization(Personalization personalization) { } /** - * Get the email's content. Content added to the returned list + * Gets the email's content. Content added to the returned list * will be included when sent. + * * @return the email's content. */ @JsonProperty("content") @@ -224,9 +241,10 @@ public List getContent() { } /** - * Add content to this email. + * Adds content to this email. + * * @param content content to add to this email. - * @return this object. + * @return {@code this} for chaining. */ public Mail content(Content content) { Content newContent = new Content() @@ -243,8 +261,9 @@ public Mail content(Content content) { } /** - * Get the email's attachments. Attachments added to the returned + * Gets the email's attachments. Attachments added to the returned * list will be included when sent. + * * @return the email's attachments. */ @JsonProperty("attachments") @@ -253,9 +272,10 @@ public List getAttachments() { } /** - * Add attachments to the email. - * @param attachment attachment to add. - * @return this object. + * Adds attachments to the email. + * + * @param attachment attachments to add. + * @return {@code this} for chaining. */ public Mail attachment(Attachment attachment) { Attachment newAttachment = new Attachment() @@ -275,7 +295,8 @@ public Mail attachment(Attachment attachment) { } /** - * Get the email's template ID. + * Gets the email's template ID. + * * @return the email's template ID. */ @JsonProperty("template_id") @@ -284,9 +305,9 @@ public String getTemplateId() { } /** - * Set the email's template ID. - * @param templateId the email's template ID. - * @return this object. + * Sets the email's template ID. + * + * @return {@code this} for chaining. */ public Mail templateId(String templateId) { this.templateId = templateId; @@ -294,8 +315,9 @@ public Mail templateId(String templateId) { } /** - * Get the email's sections. Sections added to the returned list + * Gets the email's sections. Sections added to the returned list * will be included when sent. + * * @return the email's sections. */ @JsonProperty("sections") @@ -304,11 +326,12 @@ public Map getSections() { } /** - * Add a section to the email. A section is an object of key/value - * pairs that define block sections of code to be used as substitutions. + * Adds a section to the email. A section is an object of key/value + * pairs that define block sections of code to be used as substitutions. + * * @param key the section's key. * @param value the section's value. - * @return this object. + * @return {@code this} for chaining. */ public Mail section(String key, String value) { if (sections == null) { @@ -321,8 +344,9 @@ public Mail section(String key, String value) { } /** - * Get the email's headers. Headers added to the returned list + * Gets the email's headers. Headers added to the returned list * will be included when sent. + * * @return the email's headers. */ @JsonProperty("headers") @@ -331,10 +355,11 @@ public Map getHeaders() { } /** - * Add a header to the email. + * Adds a header to the email. + * * @param key the header's key. * @param value the header's value. - * @return this object. + * @return {@code this} for chaining. */ public Mail header(String key, String value) { if (headers == null) { @@ -347,8 +372,9 @@ public Mail header(String key, String value) { } /** - * Get the email's categories. Categories added to the returned list + * Gets the email's categories. Categories added to the returned list * will be included when sent. + * * @return the email's categories. */ @JsonProperty("categories") @@ -357,9 +383,10 @@ public List getCategories() { } /** - * Add a category to the email. + * Adds a category to the email. + * * @param category the category. - * @return this object. + * @return {@code this} for chaining. */ public Mail category(String category) { if (categories == null) { @@ -372,8 +399,9 @@ public Mail category(String category) { } /** - * Get the email's custom arguments. Custom arguments added to the returned list + * Gets the email's custom arguments. Custom arguments added to the returned list * will be included when sent. + * * @return the email's custom arguments. */ @JsonProperty("custom_args") @@ -382,7 +410,7 @@ public Map getCustomArgs() { } /** - * Add a custom argument to the email. An email's custom args + * Adds a custom argument to the email. An email's custom args * are values that are specific to the entire send that will * be carried along with the email and its activity data. * Substitutions will not be made on custom arguments, so any @@ -391,9 +419,10 @@ public Map getCustomArgs() { * This parameter is overridden by personalizations[x].custom_args * if that parameter has been defined. Total custom args size * may not exceed 10,000 bytes. + * * @param key argument's key. * @param value the argument's value. - * @return this object. + * @return {@code this} for chaining. */ public Mail customArg(String key, String value) { if (customArgs == null) { @@ -406,7 +435,8 @@ public Mail customArg(String key, String value) { } /** - * Get the email's send at time (Unix timestamp). + * Gets the email's send at time (Unix timestamp). + * * @return the email's send at time. */ @JsonProperty("send_at") @@ -415,13 +445,14 @@ public long sendAt() { } /** - * Set the email's send at time. + * Sets the email's send at time. * A unix timestamp allowing you to specify when you want * your email to be delivered. This may be overridden by * the personalizations[x].send_at parameter. Scheduling - * more than 72 hours in advance is forbidden. + * more than 72 hours in advance is forbidden. + * * @param sendAt the send at time. - * @return this object. + * @return {@code this} for chaining. */ public Mail sendAt(long sendAt) { this.sendAt = sendAt; @@ -429,7 +460,8 @@ public Mail sendAt(long sendAt) { } /** - * Get the email's batch ID. + * Gets the email's batch ID. + * * @return the batch ID. */ @JsonProperty("batch_id") @@ -438,14 +470,15 @@ public String getBatchId() { } /** - * Set the email's batch ID. + * Sets the email's batch ID. * This ID represents a batch of emails to be sent at the * same time. Including a batch_id in your request allows * you include this email in that batch, and also enables * you to cancel or pause the delivery of that batch. For * more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send. + * * @param batchId the batch ID. - * @return this object. + * @return {@code this} for chaining. */ public Mail batchId(String batchId) { this.batchId = batchId; @@ -453,7 +486,8 @@ public Mail batchId(String batchId) { } /** - * Get the email's IP pool ID. + * Gets the email's IP pool ID. + * * @return the IP pool ID. */ @JsonProperty("ip_pool_name") @@ -462,9 +496,10 @@ public String getIpPoolId() { } /** - * Set the email's IP pool ID. + * Sets the email's IP pool ID. + * * @param ipPoolId the IP pool ID. - * @return this object. + * @return {@code this} for chaining. */ public Mail ipPoolId(String ipPoolId) { this.ipPoolId = ipPoolId; @@ -472,7 +507,8 @@ public Mail ipPoolId(String ipPoolId) { } /** - * Get the email's settings. + * Gets the email's settings. + * * @return the settings. */ @JsonProperty("mail_settings") @@ -481,9 +517,10 @@ public MailSettings getMailSettings() { } /** - * Set the email's settings. + * Sets the email's settings. + * * @param mailSettings the settings. - * @return this object. + * @return {@code this} for chaining. */ public Mail mailSettings(MailSettings mailSettings) { this.mailSettings = mailSettings; @@ -491,7 +528,8 @@ public Mail mailSettings(MailSettings mailSettings) { } /** - * Get the email's tracking settings. + * Gets the email's tracking settings. + * * @return the tracking settings. */ @JsonProperty("tracking_settings") @@ -500,9 +538,10 @@ public TrackingSettings getTrackingSettings() { } /** - * Set the email's tracking settings. + * Sets the email's tracking settings. + * * @param trackingSettings the tracking settings. - * @return this object. + * @return {@code this} for chaining. */ public Mail trackingSettings(TrackingSettings trackingSettings) { this.trackingSettings = trackingSettings; @@ -510,7 +549,8 @@ public Mail trackingSettings(TrackingSettings trackingSettings) { } /** - * Get the email's reply to address. + * Gets the email's reply to address. + * * @return the reply to address. */ @JsonProperty("reply_to") @@ -519,9 +559,10 @@ public Email getReplyto() { } /** - * Set the email's reply to address. + * Sets the email's reply to address. + * * @param replyTo the reply to address. - * @return this object. + * @return {@code this} for chaining. */ public Mail replyTo(Email replyTo) { this.replyTo = replyTo; @@ -529,7 +570,8 @@ public Mail replyTo(Email replyTo) { } /** - * Create a string represenation of the Mail object JSON. + * Creates a string representation of the Mail object JSON. + * * @return a JSON string. * @throws IOException in case of a JSON marshal error. */ @@ -543,7 +585,8 @@ protected String build() throws IOException { } /** - * Create a string represenation of the Mail object JSON and pretty print it. + * Creates a string representation of the Mail object JSON and pretty print it. + * * @return a pretty JSON string. * @throws IOException in case of a JSON marshal error. */ @@ -557,7 +600,8 @@ public String buildPretty() throws IOException { } /** - * Send the email. + * Sends the email. + * * @param sg the SendGrid instance to use. * @return the response object. * @throws IOException in case of a marshal, or network error. diff --git a/src/main/java/com/sendgrid/MailSettings.java b/src/main/java/com/sendgrid/MailSettings.java index 3914a455..702474d5 100644 --- a/src/main/java/com/sendgrid/MailSettings.java +++ b/src/main/java/com/sendgrid/MailSettings.java @@ -5,9 +5,8 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * An object representing a collection of different mail - * settings that you can use to specify how you would - * like this email to be handled. + * A JSON-serializable model of the settings associated with + * a given {@link Mail}. */ @JsonInclude(Include.NON_DEFAULT) public class MailSettings { @@ -28,7 +27,8 @@ public class MailSettings { private SpamCheckSettings spamCheckSettings; /** - * Get the BCC settings. + * Gets the BCC settings. + * * @return the BCC settings. */ @JsonProperty("bcc") @@ -37,9 +37,10 @@ public BCCSettings getBccSettings() { } /** - * Set the BCC settings. + * Sets the BCC settings. + * * @param bccSettings the BCC settings. - * @return this object. + * @return {@code this} for chaining. */ public MailSettings bccSettings(BCCSettings bccSettings) { this.bccSettings = bccSettings; @@ -48,10 +49,11 @@ public MailSettings bccSettings(BCCSettings bccSettings) { /** * A setting that allows you to bypass all unsubscribe - * groups and suppressions to ensure that the email is + * groups and suppressions to ensure that the email is * delivered to every single recipient. This should only * be used in emergencies when it is absolutely necessary * that every recipient receives your email. + * * @return the bypass list setting. */ @JsonProperty("bypass_list_management") @@ -60,9 +62,10 @@ public Setting getBypassListManagement() { } /** - * Set the bypass setting. + * Sets the bypass setting. + * * @param bypassListManagement the setting. - * @return this object. + * @return {@code this} for chaining. */ public MailSettings bypassListManagement(Setting bypassListManagement) { this.bypassListManagement = bypassListManagement; @@ -70,7 +73,8 @@ public MailSettings bypassListManagement(Setting bypassListManagement) { } /** - * Get the the footer settings that you would like included on every email. + * Gets the the footer settings that you would like included on every email. + * * @return the settings. */ @JsonProperty("footer") @@ -79,9 +83,10 @@ public FooterSettings getFooterSettings() { } /** - * Set the the footer settings that you would like included on every email. + * Sets the the footer settings that you would like included on every email. + * * @param footerSettings the settings. - * @return this object. + * @return {@code this} for chaining. */ public MailSettings footerSettings(FooterSettings footerSettings) { this.footerSettings = footerSettings; @@ -89,8 +94,9 @@ public MailSettings footerSettings(FooterSettings footerSettings) { } /** - * Get sandbox mode. This allows you to send a test email to + * Gets sandbox mode. This allows you to send a test email to * ensure that your request body is valid and formatted correctly. + * * @return the sandbox mode setting. */ @JsonProperty("sandbox_mode") @@ -99,9 +105,10 @@ public Setting getSandBoxMode() { } /** - * Set sandbox mode. + * Sets sandbox mode. + * * @param sandBoxMode the sandbox mode setting. - * @return this object. + * @return {@code this} for chaining. */ @JsonProperty("sandbox_mode") public MailSettings sandboxMode(Setting sandBoxMode) { @@ -110,8 +117,9 @@ public MailSettings sandboxMode(Setting sandBoxMode) { } /** - * Get the spam check settings. This allows you to test the + * Gets the spam check settings. This allows you to test the * content of your email for spam. + * * @return the spam check settings. */ @JsonProperty("spam_check") @@ -120,10 +128,11 @@ public SpamCheckSettings getSpamCheckSettings() { } /** - * Set the spam check settings. This allows you to test the + * Sets the spam check settings. This allows you to test the * content of your email for spam. + * * @param spamCheckSettings the spam check settings. - * @return this object. + * @return {@code this} for chaining. */ public MailSettings spamCheckSettings(SpamCheckSettings spamCheckSettings) { this.spamCheckSettings = spamCheckSettings; diff --git a/src/main/java/com/sendgrid/OpenTrackingSettings.java b/src/main/java/com/sendgrid/OpenTrackingSettings.java index 3b01ef50..9c4179f7 100644 --- a/src/main/java/com/sendgrid/OpenTrackingSettings.java +++ b/src/main/java/com/sendgrid/OpenTrackingSettings.java @@ -20,8 +20,10 @@ public class OpenTrackingSettings { private String substitutionTag; /** - * Determines if this setting is enabled. - * @return true if open tracking is enabled, false otherwise. + * Gets whether open tracking has been enabled. + * + * @return {@code true} if open tracking has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -29,9 +31,11 @@ public boolean getEnable() { } /** - * Set if this setting is enabled. - * @param enable true if open tracking is enabled, false otherwise. - * @return this object. + * Sets whether open tracking has been enabled. + * + * @param enable {@code true} if open tracking has been enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public OpenTrackingSettings enable(boolean enable) { this.enable = enable; @@ -39,10 +43,11 @@ public OpenTrackingSettings enable(boolean enable) { } /** - * Get the substituion tag. This allows you to specify a + * Gets the substitution tag. This allows you to specify a * substitution tag that you can insert in the body of * your email at a location that you desire. This tag will * be replaced by the open tracking pixel. + * * @return the substitution tag. */ @JsonProperty("substitution_tag") @@ -51,9 +56,10 @@ public String getSubstitutionTag() { } /** - * Set the substitution tag. + * Sets the substitution tag. + * * @param substitutionTag the substitution tag. - * @return this object. + * @return {@code this} for chaining. */ public OpenTrackingSettings substitutionTag(String substitutionTag) { this.substitutionTag = substitutionTag; diff --git a/src/main/java/com/sendgrid/Personalization.java b/src/main/java/com/sendgrid/Personalization.java index 697b1e57..c859c448 100644 --- a/src/main/java/com/sendgrid/Personalization.java +++ b/src/main/java/com/sendgrid/Personalization.java @@ -11,10 +11,11 @@ import java.util.Map; /** - * An object representing a message and its metadata. - * A personalization can be thought of as an envelope - * - it defines who should receive an individual message - * and how that message should be handled. + * A JSON-serializable model of the personalization an email + * should receive for a specific individual. + *

+ * One analogy, is an envelope - in that it defines who receives + * the email (the recipient) and how the message should be handled. */ @JsonInclude(Include.NON_DEFAULT) public class Personalization { @@ -44,14 +45,13 @@ public class Personalization { private long sendAt; /** - * Get the to list. This is an array of recipients. Each object - * within this array may contain the name, but must always - * contain the email, of a recipient. - * - * The maximum number of entries is 1000. - * - * Content added to the returned list will be included when sent. - * @return the to list. + * Gets a {@link List} view of all the email address pairs which + * should receive the email, in short - it is a view of all the + * recipients whether their name is present or otherwise. + *

+ * The maximum recipients is 1000! + * + * @return The recipients. */ @JsonProperty("to") public List getTos() { @@ -61,9 +61,11 @@ public List getTos() { } /** - * Add a recipient. + * Adds an recipient, in the form of an email address pair, to + * receive the email. + * * @param email an email address. - * @return this object. + * @return {@code this} for chaining. */ public Personalization to(Email email) { Email newEmail = new Email() @@ -80,14 +82,14 @@ public Personalization to(Email email) { } /** - * Set the CC list. This is an array of recipients. Each object - * within this array may contain the name, but must always - * contain the email, of a recipient. - * - * The maximum number of entries is 1000. - * - * Content added to the returned list will be included when sent. - * @return the CC list. + * Gets a {@link List} view of all the email address pairs which + * should receive a carbon copy of the email, in short - it is a + * view of all the recipients whether their name is present or + * otherwise. + *

+ * The maximum carbon copies is 1000! + * + * @return The recipients. */ @JsonProperty("cc") public List getCcs() { @@ -97,9 +99,11 @@ public List getCcs() { } /** - * Add a recipient. + * Adds a carbon-copy recipient, in the form of an email address pair, to + * receive the email. + * * @param email an email address. - * @return this object. + * @return {@code this} for chaining. */ public Personalization cc(Email email) { Email newEmail = new Email() @@ -116,14 +120,14 @@ public Personalization cc(Email email) { } /** - * Set the BCC list. This is an array of recipients. Each object - * within this array may contain the name, but must always - * contain the email, of a recipient. - * - * The maximum number of entries is 1000. - * - * Content added to the returned list will be included when sent. - * @return the BCC list. + * Gets a {@link List} view of all the email address pairs which + * should receive a blind carbon copy of the email, in short - it + * is a view of all the recipients whether their name is present or + * otherwise. + *

+ * The maximum blind carbon copies is 1000! + * + * @return The recipients. */ @JsonProperty("bcc") public List getBccs() { @@ -133,9 +137,11 @@ public List getBccs() { } /** - * Add a recipient. + * Adds a blind carbon-copy recipient, in the form of an email address pair, to + * receive the email. + * * @param email an email address. - * @return this object. + * @return {@code this} for chaining. */ public Personalization bcc(Email email) { Email newEmail = new Email() @@ -152,7 +158,8 @@ public Personalization bcc(Email email) { } /** - * Get the subject of the email. + * Gets the subject of the email. + * * @return the subject. */ @JsonProperty("subject") @@ -161,9 +168,10 @@ public String getSubject() { } /** - * Set the subject of the email. + * Sets the subject of the email. + * * @param subject the subject. - * @return this object. + * @return {@code this} for chaining. */ public Personalization subject(String subject) { this.subject = subject; @@ -174,11 +182,11 @@ public Personalization subject(String subject) { * Get the headers. The headers are a collection of JSON * key/value pairs allowing you to specify specific handling * instructions for your email. You may not overwrite the - * following headers: x-sg-id, x-sg-eid, received, - * dkim-signature, Content-Type, Content-Transfer-Encoding, - * To, From, Subject, Reply-To, CC, BCC - * - * Content added to the returned list will be included when sent. + * following headers: {@code x-sg-id}, {@code x-sg-eid}, + * {@code received}, {@code dkim-signature}, {@code Content-Type}, + * {@code Content-Transfer-Encoding}, {@code To}, {@code From}, + * {@code Subject}, {@code Reply-To}, {@code CC}, {@code BCC} + * * @return the headers. */ @JsonProperty("headers") @@ -189,10 +197,11 @@ public Map getHeaders() { } /** - * Add a header. + * Adds a header. + * * @param key the header key. * @param value the header value. - * @return this object. + * @return {@code this} for chaining. */ public Personalization header(String key, String value) { if (headers == null) { @@ -205,7 +214,7 @@ public Personalization header(String key, String value) { } /** - * Get the substitusions. Substitutions are a collection of + * Gets the substitusions. Substitutions are a collection of * key/value pairs following the pattern * "substitution_tag":"value to substitute". All are assumed * to be strings. These substitutions will apply to the text @@ -213,10 +222,9 @@ public Personalization header(String key, String value) { * to the subject and reply-to parameters. The total * collective size of your substitutions may not exceed * 10,000 bytes per personalization object. - * - * The maximum number of entries is 1000. - * - * Content added to the returned list will be included when sent. + *

+ * The maximum blind carbon copies is 1000! + * * @return the substitutions. */ @JsonProperty("substitutions") @@ -227,10 +235,11 @@ public Map getSubstitutions() { } /** - * Add a substitusion. + * Adds a substitution. + * * @param key the key. * @param value the value. - * @return this object. + * @return {@code this} for chaining. */ public Personalization substitution(String key, String value) { if (substitutions == null) { @@ -243,15 +252,14 @@ public Personalization substitution(String key, String value) { } /** - * Get the custom arguments. Values that are specific to + * Gets the custom arguments. Values that are specific to * this personalization that will be carried along with * the email and its activity data. Substitutions will * not be made on custom arguments, so any string that * is entered into this parameter will be assumed to be * the custom argument that you would like to be used. i * May not exceed 10,000 bytes. - * - * Content added to the returned list will be included when sent. + * * @return the custom arguments. */ @JsonProperty("custom_args") @@ -262,10 +270,11 @@ public Map getCustomArgs() { } /** - * Add a custom argument. + * Adds a custom argument. + * * @param key the key. * @param value the value. - * @return this object. + * @return {@code this} for chaining. */ public Personalization customArg(String key, String value) { if (customArgs == null) { @@ -278,10 +287,11 @@ public Personalization customArg(String key, String value) { } /** - * Get the send at time. This is a unix timestamp + * Gets the send at time. This is a unix timestamp * allowing you to specify when you want your * email to be delivered. Scheduling more than * 72 hours in advance is forbidden. + * * @return the send at time. */ @JsonProperty("send_at") @@ -290,9 +300,10 @@ public long sendAt() { } /** - * Set the send at time. + * Sets the send at time. + * * @param sendAt the send at time (Unix timestamp). - * @return this object. + * @return {@code this} for chaining. */ public Personalization sendAt(long sendAt) { this.sendAt = sendAt; diff --git a/src/main/java/com/sendgrid/SendGrid.java b/src/main/java/com/sendgrid/SendGrid.java index abeeffaa..7696e211 100644 --- a/src/main/java/com/sendgrid/SendGrid.java +++ b/src/main/java/com/sendgrid/SendGrid.java @@ -5,7 +5,7 @@ import java.util.Map; /** - * Class SendGrid allows for quick and easy access to the SendGrid API. + * A wrapper for interacting with the SendGrid API. */ public class SendGrid { /** The current library version. */ @@ -30,37 +30,46 @@ public class SendGrid { private Map requestHeaders; /** - * Construct a new SendGrid API wrapper. - * @param apiKey is your SendGrid API Key: https://app.sendgrid.com/settings/api_keys + * Creates a new SendGrid API wrapper, with the specified API key. + * + * @param apiKey the key to use with the SendGrid API. The key can be obtained from + * the SendGrid site. */ public SendGrid(String apiKey) { - this.client = new Client(); - initializeSendGrid(apiKey); + this(apiKey, new Client()); } /** - * Construct a new SendGrid API wrapper. - * @param apiKey is your SendGrid API Key: https://app.sendgrid.com/settings/api_keys - * @param test is true if you are unit testing + * Creates a new SendGrid API wrapper, with the specified API key and whether it is running + * in a unit test. + * + * @param apiKey the key to use with the SendGrid API. The key can be obtained from + * the SendGrid site. + * @param test {@code true} if the wrapper is intended for use within a unit test; + * {@code false} otherwise */ public SendGrid(String apiKey, Boolean test) { - this.client = new Client(test); - initializeSendGrid(apiKey); + this(apiKey, new Client(test)); } /** - * Construct a new SendGrid API wrapper. - * @param apiKey is your SendGrid API Key: https://app.sendgrid.com/settings/api_keys - * @param client the Client to use (allows to customize its configuration) + * Creates a new SendGrid API wrapper, with the specified API key and HTTP client. + * + * @param apiKey the key to use with the SendGrid API. The key can be obtained from + * the SendGrid site. + * @param client the HTTP client of which to use to interact with the SendGrid API. */ public SendGrid(String apiKey, Client client) { this.client = client; - initializeSendGrid(apiKey); + this.initializeSendGrid(apiKey); } /** - * Initialize the client. - * @param apiKey the user's API key. + * Populates the necessary fields for the SendGrid API wrapper to be used, with the + * specified API key. + * + * @param apiKey the key to use with the SendGrid API. The key can be obtained from + * the SendGrid site. */ public void initializeSendGrid(String apiKey) { this.apiKey = apiKey; @@ -73,31 +82,39 @@ public void initializeSendGrid(String apiKey) { } /** - * Retrieve the current library version. - * @return the current version. + * Gets the version of the library currently in use. + * + * @return the current library version. */ public String getLibraryVersion() { - return this.VERSION; + return VERSION; } /** - * Get the API version. - * @return the current API versioin (v3 by default). + * Gets the version of the SendGrid API the wrapper will be interacting with. + * + * @return the current API version (default: v3). */ public String getVersion() { return this.version; } /** - * Set the API version. - * @param version the new version. + * Sets the version of the SendGrid API the wrapper will be interacting with. + * + * All further requests to the API will have to take note of this change, as + * it affects the endpoint of which requests are made to. + * + * + * @param version the API version. */ public void setVersion(String version) { this.version = version; } /** - * Obtain the request headers. + * Gets the headers used when making requests. + * * @return the request headers. */ public Map getRequestHeaders() { @@ -105,10 +122,11 @@ public Map getRequestHeaders() { } /** - * Add a new request header. + * Adds a new header to be used when making requests. + * * @param key the header key. * @param value the header value. - * @return the new set of request headers. + * @return the updated request headers. */ public Map addRequestHeader(String key, String value) { this.requestHeaders.put(key, value); @@ -116,9 +134,10 @@ public Map addRequestHeader(String key, String value) { } /** - * Remove a request header. + * Removes a header that would have been used when making requests. + * * @param key the header key to remove. - * @return the new set of request headers. + * @return the updated request headers. */ public Map removeRequestHeader(String key) { this.requestHeaders.remove(key); @@ -126,15 +145,21 @@ public Map removeRequestHeader(String key) { } /** - * Get the SendGrid host (api.sendgrid.com by default). - * @return the SendGrid host. + * Gets the root API URL to be used when making requests. + * + * @return the SendGrid host (default: api.sendgrid.com). */ public String getHost() { return this.host; } /** - * Set the SendGrid host. + * Sets the root API URL that is used to make requests. + * + * All further requests to the API will have to take note of this change, as + * it affects the endpoint of which requests are made to. + * + * * @param host the new SendGrid host. */ public void setHost(String host) { @@ -142,17 +167,19 @@ public void setHost(String host) { } /** - * Class makeCall makes the call to the SendGrid API, override this method for testing. + * Performs a call to the SendGrid API, with the specified {@link Request}. + * * @param request the request to make. * @return the response object. * @throws IOException in case of a network error. */ public Response makeCall(Request request) throws IOException { - return client.api(request); + return this.client.api(request); } /** - * Class api sets up the request to the SendGrid API, this is main interface. + * Prepares a {@link Request}, and performs it using {@link #makeCall(Request)}. + * * @param request the request object. * @return the response object. * @throws IOException in case of a network error. diff --git a/src/main/java/com/sendgrid/Setting.java b/src/main/java/com/sendgrid/Setting.java index 4c58419e..a589ee64 100644 --- a/src/main/java/com/sendgrid/Setting.java +++ b/src/main/java/com/sendgrid/Setting.java @@ -5,7 +5,13 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * A generic setting object. + * A JSON-serializable setting that can be toggled. + *

+ * This class has the capabilities to be chained, like so: + * + * final Setting setting = new Setting() + * .enable(true); + * */ @JsonInclude(Include.NON_DEFAULT) public class Setting { @@ -14,8 +20,16 @@ public class Setting { private boolean enable; /** - * Get whether or not this setting is enabled. - * @return true if the setting is enabled, false otherwise. + * Creates a new setting. + */ + public Setting() { + } + + /** + * Gets whether the setting is enabled. + * + * @return {@code true} if the setting has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -23,9 +37,11 @@ public boolean getEnable() { } /** - * Set whether or not this setting is enabled. - * @param enable true if the setting is enabled, false otherwise. - * @return this object. + * Sets whether the setting is enabled. + * + * @param enable {@code true} if the setting is to be enabled; + * {@code false} if the setting is to be disabled. + * @return {@code this} for chaining. */ public Setting enable(boolean enable) { this.enable = enable; diff --git a/src/main/java/com/sendgrid/SpamCheckSettings.java b/src/main/java/com/sendgrid/SpamCheckSettings.java index 039f6d04..902b3e79 100644 --- a/src/main/java/com/sendgrid/SpamCheckSettings.java +++ b/src/main/java/com/sendgrid/SpamCheckSettings.java @@ -5,8 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * A setting object that allows you to test the content of - * your email for spam. + * A JSON-serializable model of the spam checking setting. + * This allows for email contents to be checked against + * criteria set out, to prevent spam. */ @JsonInclude(Include.NON_DEFAULT) public class SpamCheckSettings { @@ -21,8 +22,10 @@ public class SpamCheckSettings { private String postToUrl; /** - * Determines if this setting is enabled. - * @return true if spam checking is enabled, false otherwise. + * Gets whether spam checking has been enabled. + * + * @return {@code true} if spam checking has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -30,9 +33,11 @@ public boolean getEnable() { } /** - * Set if this setting is enabled. - * @param enable true if spam checking is enabled, false otherwise. - * @return this object. + * Sets whether spam checking has been enabled. + * + * @param enable {@code true} if spam checking has been enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public SpamCheckSettings enable(boolean enable) { this.enable = enable; @@ -40,9 +45,10 @@ public SpamCheckSettings enable(boolean enable) { } /** - * Get the the threshold used to determine if your content + * Gets the the threshold used to determine if your content * qualifies as spam on a scale from 1 to 10, with 10 being * most strict, or most likely to be considered as spam. + * * @return the threshold. */ @JsonProperty("threshold") @@ -51,9 +57,10 @@ public int getSpamThreshold() { } /** - * Set the spam check threshold. + * Sets the spam check threshold. + * * @param spamThreshold the threshold. - * @return this object. + * @return {@code this} for chaining. */ public SpamCheckSettings spamThreshold(int spamThreshold) { this.spamThreshold = spamThreshold; @@ -61,8 +68,9 @@ public SpamCheckSettings spamThreshold(int spamThreshold) { } /** - * Get the Inbound Parse URL that you would like a copy of + * Gets the Inbound Parse URL that you would like a copy of * your email along with the spam report to be sent to. + * * @return a URL. */ @JsonProperty("post_to_url") @@ -71,9 +79,10 @@ public String getPostToUrl() { } /** - * Set the Inbout Parse URL. + * Sets the Inbound Parse URL. + * * @param postToUrl a URL. - * @return this object. + * @return {@code this} for chaining. */ public SpamCheckSettings postToUrl(String postToUrl) { this.postToUrl = postToUrl; diff --git a/src/main/java/com/sendgrid/SubscriptionTrackingSettings.java b/src/main/java/com/sendgrid/SubscriptionTrackingSettings.java index a557e6a7..39d68b17 100644 --- a/src/main/java/com/sendgrid/SubscriptionTrackingSettings.java +++ b/src/main/java/com/sendgrid/SubscriptionTrackingSettings.java @@ -27,8 +27,10 @@ public class SubscriptionTrackingSettings { private String substitutionTag; /** - * Determines if this setting is enabled. - * @return true if subscription tracking is enabled, false otherwise. + * Gets whether subscription tracking has been enabled. + * + * @return {@code true} if subscription tracking has been enabled; + * {@code false} otherwise. */ @JsonProperty("enable") public boolean getEnable() { @@ -36,9 +38,11 @@ public boolean getEnable() { } /** - * Set if this setting is enabled. - * @param enable true if subscription tracking is enabled, false otherwise. - * @return this object. + * Sets whether subscription tracking is enabled. + * + * @param enable {@code true} if subscription tracking is to be enabled; + * {@code false} otherwise. + * @return {@code this} for chaining. */ public SubscriptionTrackingSettings enable(boolean enable) { this.enable = enable; @@ -46,9 +50,10 @@ public SubscriptionTrackingSettings enable(boolean enable) { } /** - * Get the plain text to be appended to the email, with the + * Gets the plain text to be appended to the email, with the * subscription tracking link. You may control where - * the link is by using the tag <% %> + * the link is by using the tag {@code <% %>}. + * * @return the plain text. */ @JsonProperty("text") @@ -57,9 +62,10 @@ public String getText() { } /** - * Set the plain text. + * Sets the plain text. + * * @param text the plain text. - * @return this object. + * @return {@code this} for chaining. */ public SubscriptionTrackingSettings text(String text) { this.text = text; @@ -67,9 +73,10 @@ public SubscriptionTrackingSettings text(String text) { } /** - * Get the HTML to be appended to the email, with the + * Gets the HTML to be appended to the email, with the * subscription tracking link. You may control where - * the link is by using the tag <% %> + * the link is by using the tag {@code <% %>}. + * * @return the HTML. */ @JsonProperty("html") @@ -78,9 +85,10 @@ public String getHtml() { } /** - * Set the HTML. + * Sets the HTML. + * * @param html the HTML. - * @return this object. + * @return {@code this} for chaining. */ public SubscriptionTrackingSettings html(String html) { this.html = html; @@ -88,12 +96,13 @@ public SubscriptionTrackingSettings html(String html) { } /** - * Get the tag that will be replaced with the - * unsubscribe URL. for example: [unsubscribe_url]. + * Gets the tag that will be replaced with the + * unsubscribe URL. for example: {@code [unsubscribe_url]}. * If this parameter is used, it will override both * the text and html parameters. The URL of the link * will be placed at the substitution tag’s location, * with no additional formatting. + * * @return the substitution tag. */ @JsonProperty("substitution_tag") @@ -102,9 +111,10 @@ public String getSubstitutionTag() { } /** - * Set the substitution tag. + * Sets the substitution tag. + * * @param substitutionTag the substitution tag. - * @return this object. + * @return {@code this} for chaining. */ public SubscriptionTrackingSettings substitutionTag(String substitutionTag) { this.substitutionTag = substitutionTag; diff --git a/src/main/java/com/sendgrid/TrackingSettings.java b/src/main/java/com/sendgrid/TrackingSettings.java index 28de949a..b88eb96b 100644 --- a/src/main/java/com/sendgrid/TrackingSettings.java +++ b/src/main/java/com/sendgrid/TrackingSettings.java @@ -5,9 +5,8 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * An object representing the settings to determine how - * you would like to track the metrics of how your recipients - * interact with your email. + * A JSON-serializable model of the settings defining how metrics + * tracking should be performed for recipient interactions. */ @JsonInclude(Include.NON_DEFAULT) public class TrackingSettings { @@ -25,9 +24,10 @@ public class TrackingSettings { private GoogleAnalyticsSettings googleAnalyticsSettings; /** - * Get the click tracking settings. Click tracking allows you to + * Gets the click tracking settings. Click tracking allows you to * track whether a recipient clicked a link in your email. - * @return the settings. + * + * @return the click tracking settings. */ @JsonProperty("click_tracking") public ClickTrackingSettings getClickTrackingSettings() { @@ -35,9 +35,10 @@ public ClickTrackingSettings getClickTrackingSettings() { } /** - * Set the click tracking settings. - * @param clickTrackingSettings the settings. - * @return this object. + * Sets the click tracking settings. + * + * @param clickTrackingSettings the new click tracking settings. + * @return {@code this} for chaining. */ public TrackingSettings clickTrackingSettings(ClickTrackingSettings clickTrackingSettings) { this.clickTrackingSettings = clickTrackingSettings; @@ -45,10 +46,12 @@ public TrackingSettings clickTrackingSettings(ClickTrackingSettings clickTrackin } /** - * Get the open tracking settings. The open tracking allows you to - * track whether the email was opened or not, but including a single - * pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened. - * @return the settings. + * Gets the open tracking settings. The open tracking allows you to + * track whether the email was opened or not, by including a single + * pixel image in the body of the content. When the pixel is loaded, + * we can log that the email was opened. + * + * @return the open tracking settings. */ @JsonProperty("open_tracking") public OpenTrackingSettings getOpenTrackingSettings() { @@ -56,9 +59,10 @@ public OpenTrackingSettings getOpenTrackingSettings() { } /** - * Set the open tracking settings. - * @param openTrackingSettings the settings. - * @return this object. + * Sets the open tracking settings. + * + * @param openTrackingSettings the open tracking settings. + * @return {@code this} for chaining. */ public TrackingSettings openTrackingSettings(OpenTrackingSettings openTrackingSettings) { this.openTrackingSettings = openTrackingSettings; @@ -66,11 +70,13 @@ public TrackingSettings openTrackingSettings(OpenTrackingSettings openTrackingSe } /** - * Get the subscription tracking settings. The subscription + * Gets the subscription tracking settings. The subscription * tracking setting allows you to insert a subscription - * management link at the bottom of the text and html bodies + * management link at the bottom of the text and html body * of your email. If you would like to specify the location - * of the link within your email, you may use the substitution_tag. + * of the link within your email, you may use the + * {@code substitution_tag}. + * * @return the settings. */ @JsonProperty("subscription_tracking") @@ -79,9 +85,10 @@ public SubscriptionTrackingSettings getSubscriptionTrackingSettings() { } /** - * Set the subscription tracking settings. - * @param subscriptionTrackingSettings the settings. - * @return this object. + * Sets the subscription tracking settings. + * + * @param subscriptionTrackingSettings the subscription tracking settings. + * @return {@code this} for chaining. */ public TrackingSettings subscriptionTrackingSetting(SubscriptionTrackingSettings subscriptionTrackingSettings) { this.subscriptionTrackingSettings = subscriptionTrackingSettings; @@ -89,9 +96,10 @@ public TrackingSettings subscriptionTrackingSetting(SubscriptionTrackingSettings } /** - * Get the Google Analytics settings. This setting allows you to + * Gets the Google Analytics settings. This setting allows you to * enable tracking provided by Google Analytics. - * @return the settings. + * + * @return the google analytics settings. */ @JsonProperty("ganalytics") public GoogleAnalyticsSettings getGoogleAnalyticsSettings() { @@ -99,9 +107,10 @@ public GoogleAnalyticsSettings getGoogleAnalyticsSettings() { } /** - * Set the Google Analytics settings. - * @param googleAnalyticsSettings the settings. - * @return this object. + * Sets the Google Analytics settings. + * + * @param googleAnalyticsSettings the google analytics settings. + * @return {@code this} for chaining. */ public TrackingSettings googleAnalyticsSettings(GoogleAnalyticsSettings googleAnalyticsSettings) { this.googleAnalyticsSettings = googleAnalyticsSettings;