S3 Event Notification javadoc improvement (#5063)

* S3 Event Notification java-doc improvement.

* S3 Event Notification java-doc improvement.

Author: L-Applin

.changes/next-release/documentation-S3-d8833b5.json

@@ -0,0 +1,6 @@
+{
+    "type": "documentation",
+    "category": "S3",
+    "contributor": "",
+    "description": "improve javadoc for S3 Event Notification module."
+}

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/IntelligentTieringEventData.java

@@ -21,7 +21,9 @@
 import software.amazon.awssdk.utils.ToString;
 
 /**
- * The IntelligentTieringEventData key is only visible for S3 Intelligent-Tiering events.
+ * The IntelligentTieringEventData key is only visible for
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html">S3 Intelligent-Tiering</a>
+ * related events.
  */
 @SdkPublicApi
 public class IntelligentTieringEventData {

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/LifecycleEventData.java

@@ -21,7 +21,9 @@
 import software.amazon.awssdk.utils.ToString;
 
 /**
- * The LifecycleEventData is only visible for S3 Lifecycle transition events.
+ * The LifecycleEventData is only visible for
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-transition-general-considerations.html">
+ *     S3 Lifecycle transition</a> related events.
  */
 @SdkPublicApi
 public class LifecycleEventData {

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/ReplicationEventData.java

@@ -21,7 +21,8 @@
 import software.amazon.awssdk.utils.ToString;
 
 /**
- * The ReplicationEventData is only visible for replication events.
+ * The ReplicationEventData is only visible for
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html">replication</a> related events.
  */
 @SdkPublicApi
 public class ReplicationEventData {

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/ResponseElements.java

@@ -19,6 +19,12 @@
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.utils.ToString;
 
+/**
+ * The responseElements key value is useful if you want to trace a request by following up with AWS Support.
+ * Both x-amz-request-id and x-amz-id-2 help Amazon S3 trace an individual request. These values are the same as those that
+ * Amazon S3 returns in the response to the request that initiates the events. This is so they can be used to match the event
+ * to the request.
+ */
 @SdkPublicApi
 public class ResponseElements {
 

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/S3.java

@@ -19,6 +19,11 @@
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.utils.ToString;
 
+/**
+ * The s3 key provides information about the bucket and object involved in the event. The object key name value is URL encoded.
+ * For example, "red flower.jpg" becomes "red+flower.jpg" (Amazon S3 returns "application/x-www-form-urlencoded" as the content
+ * type in the response).
+ */
 @SdkPublicApi
 public class S3 {
 
@@ -34,14 +39,24 @@ public S3(String configurationId, S3Bucket bucket, S3Object object, String s3Sch
         this.s3SchemaVersion = s3SchemaVersion;
     }
 
+    /**
+     * @return the ID found in the bucket notification configuration
+     */
     public String getConfigurationId() {
         return configurationId;
     }
 
+    /**
+     * @return the bucket information.
+     */
     public S3Bucket getBucket() {
         return bucket;
     }
 
+    /**
+     *
+     * @return
+     */
     public S3Object getObject() {
         return object;
     }

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/S3Bucket.java

@@ -20,6 +20,9 @@
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.utils.ToString;
 
+/**
+ * Bucket information.
+ */
 @SdkPublicApi
 public class S3Bucket {
 
@@ -33,14 +36,23 @@ public S3Bucket(String name, UserIdentity ownerIdentity, String arn) {
         this.arn = arn;
     }
 
+    /**
+     * @return the bucket name.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * @return the user identity containing the Amazon customer ID of the bucket owner.
+     */
     public UserIdentity getOwnerIdentity() {
         return ownerIdentity;
     }
 
+    /**
+     * @return The bucket ARN.
+     */
     public String getArn() {
         return arn;
     }

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/S3EventNotification.java

@@ -25,7 +25,11 @@
 import software.amazon.awssdk.utils.ToString;
 
 /**
- * A helper class that represents a strongly typed S3 EventNotification item sent to SQS, SNS, or Lambda.
+ * A helper class that represents a strongly typed S3 Event Notification item sent to SQS, SNS, or Lambda. For more information
+ * about Amazon S3 Event Notifications, visit the
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventNotifications.html">S3 User Guide</a>.
+ * This class can be used to parse notification messages in the json format or to serialize a S3EventNotification instance to
+ * json.
  */
 @SdkPublicApi
 public class S3EventNotification {
@@ -40,23 +44,58 @@ public List<S3EventNotificationRecord> getRecords() {
         return records;
     }
 
+    /**
+     * Converts a json representation of the notification message to an instance of S3EventNotification. Any missing fields
+     * of the json will be null in the resulting object.
+     * Any extra fields will be ignored.
+     * @param json the notification message in json format
+     * @return an instance of notification message S3EventNotification
+     */
     public static S3EventNotification fromJson(String json) {
         return S3EventNotificationReader.create().read(json);
     }
 
-
+    /**
+     * Converts a json representation of the notification message to an instance of S3EventNotification. Any missing fields
+     * of the json will be null in the resulting object.
+     * Any extra fields will be ignored.
+     * @param json the notification message in json format
+     * @return an instance of notification message S3EventNotification
+     */
     public static S3EventNotification fromJson(byte[] json) {
         return S3EventNotificationReader.create().read(json);
     }
 
+    /**
+     * Converts a json representation of the notification message to an instance of S3EventNotification. Any missing fields
+     * of the json will be null in the resulting object.
+     * Any extra fields will be ignored.
+     * @param json the notification message in json format
+     * @return an instance of notification message S3EventNotification
+     */
     public S3EventNotification fromJson(InputStream json) {
         return S3EventNotificationReader.create().read(json);
     }
 
+    /**
+     * Serialize this instance to json format. {@link GlacierEventData}, {@link ReplicationEventData},
+     * {@link IntelligentTieringEventData} and {@link LifecycleEventData} keys
+     * will be excluded from the json if {@code null}. Any other null fields of the object will be serialized as
+     * json {@code null}.
+     * @return the json representation of this class.
+     */
     public String toJson() {
         return S3EventNotificationWriter.create().writeToString(this);
     }
 
+    /**
+     * Serialize this instance to json format, with new line and correct indentation levels. {@link GlacierEventData},
+     * {@link ReplicationEventData},
+     * {@link IntelligentTieringEventData} and {@link LifecycleEventData} keys
+     * will be excluded from the json if {@code null}. Any other null fields of the object will be serialized as
+     * json {@code null}.
+     * @return the json representation of this class.
+     */
     public String toJsonPretty() {
         S3EventNotificationWriter writer = S3EventNotificationWriter.builder()
                                                                     .prettyPrint(true)

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/S3EventNotificationRecord.java

@@ -21,6 +21,12 @@
 import software.amazon.awssdk.annotations.SdkTestInternalApi;
 import software.amazon.awssdk.utils.ToString;
 
+/**
+ * A record representing a notification for a single event. The
+ * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-content-structure.html">Event message structure</a>
+ * page of S3 user guide contains additional information about the different fields of the
+ * notification record.
+ */
 @SdkPublicApi
 public class S3EventNotificationRecord {
 
@@ -101,50 +107,116 @@ public String getAwsRegion() {
         return awsRegion;
     }
 
+    /**
+     * The name of the event type for this notification. For more information about the various event type, visit the
+     * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html#supported-notification-event-types">
+     *     Event notification types and destinations
+     *     </a> page of S3 user guide.
+     * It references the list of event notification types but doesn't contain the s3: prefix.
+     * @return the event name.
+     */
     public String getEventName() {
         return eventName;
     }
 
+
+    /**
+     * The service from which this event was generated, usually {@code "aws:s3"}.
+     * @return the event source.
+     */
     public String getEventSource() {
         return eventSource;
     }
 
+    /**
+     * @return The time, in ISO-8601 format, for example, 1970-01-01T00:00:00.000Z, when Amazon S3 finished processing the
+     * request.
+     */
     public Instant getEventTime() {
         return eventTime;
     }
 
+    /**
+     * The eventVersion key value contains a major and minor version in the form {@code <major>.<minor>}.
+     * @return the event version.
+     */
     public String getEventVersion() {
         return eventVersion;
     }
 
+    /**
+     * Request Parameters contains the {@code sourceIPAddress} field, which is the ip address where request came from.
+     * @return the request parameter containing the source IP address.
+     */
     public RequestParameters getRequestParameters() {
         return requestParameters;
     }
 
+    /**
+     * The responseElements key value is useful if you want to trace a request by following up with AWS Support.
+     * Both x-amz-request-id and x-amz-id-2 help Amazon S3 trace an individual request.
+     * These values are the same as those that Amazon S3 returns in the response to the request that initiates the events.
+     * This is so they can be used to match the event to the request.
+     * @return The response element containing the trace information.
+     */
     public ResponseElements getResponseElements() {
         return responseElements;
     }
 
+    /**
+     * Contains information about the bucket and object involved in the event. The object key name value is URL encoded. For
+     * example, "red flower.jpg" becomes "red+flower.jpg" (Amazon S3 returns "application/x-www-form-urlencoded" as the
+     * content type in the response).
+     * @return the instance of {@link S3} containing object information.
+     */
     public S3 getS3() {
         return s3;
     }
 
+    /**
+     * The user identity contains the {@code principalId} field, which has the Amazon customer ID of the user who caused the
+     * event.
+     * @return the user identity containing the {@code principalId}.
+     */
     public UserIdentity getUserIdentity() {
         return userIdentity;
     }
 
+    /**
+     * The GlacierEventData is only visible for s3:ObjectRestore:Completed events.
+     * Contains information related to restoring an archived object. For more information about archive and storage classes, see
+     * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/restoring-objects.html">Restoring an archived object</a>
+     * @return the glacier event data.
+     */
     public GlacierEventData getGlacierEventData() {
         return glacierEventData;
     }
 
+    /**
+     * The LifecycleEventData is only visible for
+     * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-transition-general-considerations.html">
+     *     S3 Lifecycle transition</a> related events.
+     * @return the lifecycle event data.
+     */
     public LifecycleEventData getLifecycleEventData() {
         return lifecycleEventData;
     }
 
+    /**
+     * The IntelligentTieringEventData key is only visible for
+     * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html">S3 Intelligent-Tiering</a>
+     * related events.
+     * @return the intelligent tiering event data.
+     */
     public IntelligentTieringEventData getIntelligentTieringEventData() {
         return intelligentTieringEventData;
     }
 
+    /**
+     * The ReplicationEventData is only visible for
+     * <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html">replication</a> related events.
+     * @return
+     */
     public ReplicationEventData getReplicationEventData() {
         return replicationEventData;
     }

services-custom/s3-event-notifications/src/main/java/software/amazon/awssdk/eventnotifications/s3/model/S3Object.java

@@ -22,6 +22,9 @@
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.utils.ToString;
 
+/**
+ * Object information.
+ */
 @SdkPublicApi
 public class S3Object {
 
@@ -39,6 +42,9 @@ public S3Object(String key, Long size, String eTag, String versionId, String seq
         this.sequencer = sequencer;
     }
 
+    /**
+     * @return the object key.
+     */
     public String getKey() {
         return key;
     }
@@ -57,18 +63,33 @@ public String getUrlDecodedKey() {
         }
     }
 
+    /**
+     * @return the object size in bytes.
+     */
     public Long getSizeAsLong() {
         return size;
     }
 
+    /**
+     * @return the object eTag
+     */
     public String getETag() {
         return eTag;
     }
 
+    /**
+     * @return the object version if bucket is versioning-enabled, otherwise null
+     */
     public String getVersionId() {
         return versionId;
     }
 
+    /**
+     * The sequencer key provides a way to determine the sequence of events. Event notifications aren't guaranteed to arrive in
+     * the same order that the events occurred. However, notifications from events that create objects (PUTs) and delete
+     * objects contain a sequencer. It can be used to determine the order of events for a given object key.
+     * @return A string representation of a hexadecimal value used to determine event sequence, only used with PUTs and DELETEs.
+     */
     public String getSequencer() {
         return sequencer;
     }