chore: add upgrade guide and readme updates

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+[2024-06-27] Version 5.0.0-rc.0
+--------------------------------
+- Release Candidate prep
+
 [2024-02-14] Version 4.10.2
 ---------------------------
 **Library - Chore**

README.md

@@ -90,94 +90,112 @@ You can just drop the jar file in. It's a fat jar - it has all the dependencies
 <a name="quick-start"></a>
 # Quick Start
 
-## Hello Email
-
-The following is the minimum needed code to send an email with the [/mail/send Helper](src/main/java/com/sendgrid/helpers) ([here](examples/helpers/mail/Example.java#L30) is a full example):
-
-### With Mail Helper Class
+## Alerts API
+Sendgrid provides an API for sending alerts. The following is the minimum needed code to send an alert using the Java Helper Library:
 
+### Create Alerts
 ```java
 import com.sendgrid.*;
 import java.io.IOException;
 
 public class Example {
-  public static void main(String[] args) throws IOException {
-    Email from = new Email("[email protected]");
-    String subject = "Sending with Twilio SendGrid is Fun";
-    Email to = new Email("[email protected]");
-    Content content = new Content("text/plain", "and easy to do anywhere, even with Java");
-    Mail mail = new Mail(from, subject, to, content);
-
-    SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
-    Request request = new Request();
+  public static void main(String[] args) {
+      ApiKeySendGrid.init(System.getenv("SENDGRID_API_KEY"));
+      CreateAlertRequest createAlertRequest = new CreateAlertRequest.Builder(Type.USAGE_LIMIT, "[email protected]").percentage(50).build();
     try {
-      request.setMethod(Method.POST);
-      request.setEndpoint("mail/send");
-      request.setBody(mail.build());
-      Response response = sg.api(request);
-      System.out.println(response.getStatusCode());
-      System.out.println(response.getBody());
-      System.out.println(response.getHeaders());
-    } catch (IOException ex) {
-      throw ex;
+        CreateAlert createAlert =  new CreateAlert();
+        createAlert.setCreateAlertRequest(createAlertRequest);
+        ApiResponse apiResponse = createAlert.send();
+        System.out.println(response.getStatusCode());
+        System.out.println(response.getBody());
+        System.out.println(response.getHeaders());
+    } catch (ApiErrorResponse apiErrorResponse)  {
+        System.out.println(apiErrorResponse.getMessage());
     }
   }
 }
 ```
 
-The `Mail` constructor creates a [personalization object](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/personalizations.html) for you. [Here](examples/helpers/mail/Example.java#L221) is an example of how to add to it.
-
-### Without Mail Helper Class
-
-The following is the minimum needed code to send an email without the /mail/send Helper ([here](examples/mail/mail.java#L54) is a full example):
-
+### Fetch a specific alert
 ```java
 import com.sendgrid.*;
 import java.io.IOException;
 
 public class Example {
-  public static void main(String[] args) throws IOException {
+  public static void main(String[] args) {
+      ApiKeySendGrid.init(System.getenv("SENDGRID_API_KEY"));
+      GetAlert getAlert = new GetAlert(xxxxxxx); // alert id
+      ApiResponse getAlertResponse = null;
     try {
-      SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
-      Request request = new Request();
-      request.setMethod(Method.POST);
-      request.setEndpoint("mail/send");
-      request.setBody("{\"personalizations\":[{\"to\":[{\"email\":\"[email protected]\"}],\"subject\":\"Sending with Twilio SendGrid is Fun\"}],\"from\":{\"email\":\"[email protected]\"},\"content\":[{\"type\":\"text/plain\",\"value\": \"and easy to do anywhere, even with Java\"}]}");
-      Response response = sg.api(request);
-      System.out.println(response.getStatusCode());
-      System.out.println(response.getBody());
-      System.out.println(response.getHeaders());
-    } catch (IOException ex) {
-      throw ex;
+        getAlertResponse = getAlert.send();
+        GetAlert200Response alert = (GetAlert200Response) getAlertResponse.getBody();
+        System.out.println(alert);
+    } catch (ApiErrorResponse apiErrorResponse)  {
+        System.out.println(apiErrorResponse.getMessage());
     }
   }
 }
 ```
 
-## General v3 Web API Usage
-
+### List all alerts
 ```java
 import com.sendgrid.*;
 import java.io.IOException;
 
 public class Example {
-  public static void main(String[] args) throws IOException {
-    SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
+  public static void main(String[] args) {
+      ApiKeySendGrid.init(System.getenv("SENDGRID_API_KEY"));
+      ListAlert listAlert = new ListAlert();
+      ApiResponse getAlert = null;
     try {
-      Request request = new Request();
-      request.setMethod(Method.GET);
-      request.setEndpoint("api_keys");
-      Response response = sg.api(request);
-      System.out.println(response.getStatusCode());
-      System.out.println(response.getBody());
-      System.out.println(response.getHeaders());
-    } catch (IOException ex) {
-      throw ex;
+        getAlert = listAlert.send();
+        List<ListAlert200ResponseInner> body = (List<ListAlert200ResponseInner>)getAlert.getBody();
+        System.out.println(body);
+    } catch (ApiErrorResponse apiErrorResponse)  {
+        System.out.println(apiErrorResponse.getMessage());
     }
   }
 }
 ```
 
+### Delete a specific alert
+```java
+import com.sendgrid.*;
+import java.io.IOException;
+
+public class Example {
+    public static void main(String[] args) {
+        ApiKeySendGrid.init(System.getenv("SENDGRID_API_KEY"));
+        DeleteAlert deleteAlert = new DeleteAlert(xxxxxxx); // alert id
+        ApiResponse deleteAlertResponse;
+        try {
+            deleteAlertResponse = deleteAlert.send();
+            System.out.println(deleteAlertResponse.getStatusCode());
+            System.out.println(deleteAlertResponse.getBody());
+            System.out.println(deleteAlertResponse.getHeaders());
+
+        } catch (ApiErrorResponse apiErrorResponse)  {
+            System.out.println(apiErrorResponse.getMessage());
+        }
+    }
+}
+```
+
+## Hello Email
+
+You can send an email with the [/mail/send Helper](src/main/java/com/sendgrid/helpers) ([here](examples/helpers/mail/Example.java#L30) is a full example).
+
+### With Mail Helper Class
+The `Mail` constructor creates a [personalization object](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/personalizations.html) for you. [Here](examples/helpers/mail/Example.java#L221) is an example of how to add to it.
+
+### Without Mail Helper Class
+
+You can also send an email without the /mail/send Helper ([here](examples/mail/mail.java#L54) is a full example).
+
+## General v3 Web API Usage
+
+[Here](examples/apikeys/apikeys.java) is the full example of using v3 web API.
+
 <a name="usage"></a>
 # Usage
 

UPGRADE.md

@@ -0,0 +1,11 @@
+# Upgrade Guide
+
+_`MAJOR` version bumps will have upgrade notes posted here._
+
+[2023-10-XX] 4.x.x to 5.x.x-rc.x
+--------------------------------
+### Overview
+
+#### Sendgrid Java Helper Library’s major version 5.0.0-rc.x is now available. We ensured that you can upgrade to Java helper Library 5.0.0-rc.x version without any breaking changes
+
+Behind the scenes Java Helper is now auto-generated via OpenAPI with this release. This enables us to rapidly add new features and enhance consistency across versions and languages.

pom.xml

@@ -159,6 +159,17 @@
             <artifactId>maven-scm-provider-gitexe</artifactId>
             <version>1.8.1</version>
           </dependency>
+          <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>1.18.30</version>
+            <scope>compile</scope>
+          </dependency>
+          <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>1.7.30</version>
+          </dependency>
         </dependencies>
       </plugin>
       <plugin>
@@ -245,10 +256,12 @@
             <artifactId>spotbugs</artifactId>
             <version>4.0.4</version>
           </dependency>
+
         </dependencies>
       </plugin>
     </plugins>
   </build>
+
   <developers>
     <developer>
       <id>thinkingserious</id>
@@ -264,6 +277,11 @@
       <artifactId>java-http-client</artifactId>
       <version>4.5.0</version>
     </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.datatype</groupId>
+      <artifactId>jackson-datatype-jsr310</artifactId>
+      <version>${jackson.version}</version>
+    </dependency>
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-core</artifactId>
@@ -296,6 +314,17 @@
       <artifactId>bcprov-jdk18on</artifactId>
       <version>1.76</version>
     </dependency>
+    <dependency>
+      <groupId>org.projectlombok</groupId>
+      <artifactId>lombok</artifactId>
+      <version>1.18.30</version>
+      <scope>compile</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+      <version>1.7.30</version>
+    </dependency>
   </dependencies>
   <reporting>
     <plugins>

src/main/java/com/sendgrid/ApiKeySendGrid.java

@@ -0,0 +1,97 @@
+package com.sendgrid;
+
+import com.sendgrid.constant.EnumConstants;
+import com.sendgrid.constant.ErrorMessages;
+import com.sendgrid.exception.AuthenticationException;
+import com.sendgrid.http.ApiKeyRestClient;
+import lombok.Getter;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+public class ApiKeySendGrid {
+    private static String apiKey = System.getenv("SENDGRID_API_KEY");
+    private static String region = System.getenv("SENDGRID_REGION");
+    @Getter
+    private static List<String> userAgentExtensions;
+    private static volatile ApiKeyRestClient apiKeyRestClient;
+
+    private ApiKeySendGrid() {
+    }
+
+    public static synchronized void init(final String apiKey) {
+        if (apiKey == null || apiKey.isEmpty()) {
+            throw new AuthenticationException(String.format(ErrorMessages.EMPTY_STRING, "API_KEY"));
+        }
+        ApiKeySendGrid.apiKey = apiKey;
+    }
+
+
+    // Explore Data Residency
+    /**
+     * Set the region.
+     *
+     * @param region region to make request
+     * Global Region api.sendgrid.com
+     * EU Region api.eu.sendgrid.com
+     */
+    public static synchronized void setRegion(final String region) {
+        if (region == null || region.isEmpty()) {
+            throw new AuthenticationException(String.format(ErrorMessages.EMPTY_STRING, "REGION"));
+        }
+        if (!EnumConstants.Region.getValues().contains(region)) {
+            throw new AuthenticationException(String.format(ErrorMessages.INVALID_STRING, "REGION"));
+        }
+        if (!Objects.equals(region, ApiKeySendGrid.region)) {
+            ApiKeySendGrid.invalidate();
+        }
+        ApiKeySendGrid.region = region;
+    }
+
+    public static synchronized void setUserAgentExtensions(final List<String> userAgentExtensions) {
+        if (userAgentExtensions != null && !userAgentExtensions.isEmpty()) {
+            ApiKeySendGrid.userAgentExtensions = new ArrayList<>(userAgentExtensions);
+        } else {
+            // In case a developer wants to reset userAgentExtensions
+            ApiKeySendGrid.userAgentExtensions = null;
+        }
+    }
+
+
+    public static ApiKeyRestClient getRestClient() {
+        if (ApiKeySendGrid.apiKeyRestClient == null) {
+            synchronized (ApiKeySendGrid.class) {
+                if (ApiKeySendGrid.apiKeyRestClient == null) {
+                    ApiKeySendGrid.apiKeyRestClient = buildRestClient();
+                }
+            }
+        }
+
+        return ApiKeySendGrid.apiKeyRestClient;
+    }
+
+    private static ApiKeyRestClient buildRestClient() {
+        if (ApiKeySendGrid.apiKey == null) {
+            throw new AuthenticationException(
+                    "Api Key is not initialized, please call ApiKeySendGrid.init()"
+            );
+        }
+        ApiKeyRestClient.Builder builder = new ApiKeyRestClient.Builder(ApiKeySendGrid.apiKey);
+        if (userAgentExtensions != null) {
+            builder.userAgentExtensions(ApiKeySendGrid.userAgentExtensions);
+        }
+        if (region == null)
+            builder.region(EnumConstants.Region.GLOBAL.getValue());
+        else 
+            builder.region(region);
+        return builder.build();
+    }
+
+    /**
+     * Invalidates the volatile state held in the Sendgrid singleton.
+     */
+    private static void invalidate() {
+        ApiKeySendGrid.apiKeyRestClient = null;
+    }
+}

src/main/java/com/sendgrid/base/apikey/ApiKeyBase.java

@@ -0,0 +1,17 @@
+package com.sendgrid.base.apikey;
+
+import com.sendgrid.ApiKeySendGrid;
+import com.sendgrid.constant.ErrorMessages;
+import com.sendgrid.http.ApiResponse;
+import com.sendgrid.http.ApiKeyRestClient;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public abstract class ApiKeyBase {
+    private static final Logger logger = LoggerFactory.getLogger(ApiKeyBase.class);
+    public ApiResponse send() {
+        logger.debug(String.format(ErrorMessages.DEFAULT_REST_CLIENT, "ApiKeyBase"));
+        return send(ApiKeySendGrid.getRestClient());
+    }
+    public abstract ApiResponse send(final ApiKeyRestClient client);
+}

src/main/java/com/sendgrid/constant/ApplicationConstants.java

@@ -0,0 +1,15 @@
+package com.sendgrid.constant;
+
+import lombok.AccessLevel;
+import lombok.NoArgsConstructor;
+
+import java.util.function.Predicate;
+
+
+@NoArgsConstructor(access = AccessLevel.PRIVATE)
+public class ApplicationConstants {
+    public static final int HTTP_STATUS_CODE_CREATED = 201;
+    public static final int HTTP_STATUS_CODE_NO_CONTENT = 204;
+    public static final int HTTP_STATUS_CODE_OK = 200;
+    public static final Predicate<Integer> SUCCESS = i -> i != null && i >= 200 && i < 400;
+}

src/main/java/com/sendgrid/constant/Config.java

@@ -0,0 +1,11 @@
+package com.sendgrid.constant;
+
+import lombok.experimental.UtilityClass;
+
+@UtilityClass
+public class Config {
+    public static final String VERSION = "5.0.0-rc.0";
+    public static final String JAVA_VERSION = System.getProperty("java.version");
+    public static final String OS_NAME = System.getProperty("os.name");
+    public static final String OS_ARCH = System.getProperty("os.arch");
+}