Annotate and document members that are modeled as deprecated...

.changes/next-release/feature-AWSSDKforJavav2-eac6282.json

@@ -0,0 +1,6 @@
+{
+    "category": "AWS SDK for Java v2", 
+    "contributor": "", 
+    "type": "feature", 
+    "description": "Annotate and document members that are modeled as deprecated"
+}

codegen/src/main/java/software/amazon/awssdk/codegen/AddShapes.java

@@ -79,6 +79,7 @@ protected final ShapeModel generateShapeModel(String javaClassName, String shape
         // contains the list of c2j member names that are required for this shape.
         shapeModel.setRequired(shape.getRequired());
         shapeModel.setDeprecated(shape.isDeprecated());
+        shapeModel.setDeprecatedMessage(shape.getDeprecatedMessage());
         shapeModel.setWrapper(shape.isWrapper());
         shapeModel.withIsEventStream(shape.isEventstream());
         shapeModel.withIsEvent(shape.isEvent());
@@ -172,6 +173,7 @@ private MemberModel generateMemberModel(String c2jMemberName, Member c2jMemberDe
                    .withJsonValue(c2jMemberDefinition.getJsonvalue());
         memberModel.setDocumentation(c2jMemberDefinition.getDocumentation());
         memberModel.setDeprecated(c2jMemberDefinition.isDeprecated());
+        memberModel.setDeprecatedMessage(c2jMemberDefinition.getDeprecatedMessage());
         memberModel.setSensitive(isSensitiveShapeOrContainer(c2jMemberDefinition, allC2jShapes));
         memberModel
                 .withFluentGetterMethodName(namingStrategy.getFluentGetterMethodName(c2jMemberName, parentShape, shape))

codegen/src/main/java/software/amazon/awssdk/codegen/customization/processors/ShapeModifiersProcessor.java

@@ -208,7 +208,13 @@ private void preprocessModifyShapeMembers(ServiceModel serviceModel, Shape shape
 
     private void doModifyShapeMembers(ServiceModel serviceModel, Shape shape, String memberToModify,
                                       ModifyModelShapeModifier modifyModel) {
-
+        if (modifyModel.isDeprecated()) {
+            Member member = shape.getMembers().get(memberToModify);
+            member.setDeprecated(true);
+            if (modifyModel.getDeprecatedMessage() != null) {
+                member.setDeprecatedMessage(modifyModel.getDeprecatedMessage());
+            }
+        }
         // Currently only supports emitPropertyName which is to rename the member
         if (modifyModel.getEmitPropertyName() != null) {
             Member member = shape.getMembers().remove(memberToModify);

codegen/src/main/java/software/amazon/awssdk/codegen/model/config/customization/ModifyModelShapeModifier.java

@@ -17,6 +17,16 @@
 
 public class ModifyModelShapeModifier {
 
+    /**
+     * Indicates whether a member should be annotated as {@link Deprecated}.
+     */
+    private boolean deprecated;
+
+    /**
+     * The Javadoc message that will be included with the {@link Deprecated} annotation.
+     */
+    private String deprecatedMessage;
+
     /**
      * Indicates whether a renamed member should create getters and setters under the existing name
      */
@@ -49,6 +59,22 @@ public class ModifyModelShapeModifier {
 
     private String unmarshallLocationName;
 
+    public String getDeprecatedMessage() {
+        return deprecatedMessage;
+    }
+
+    public void setDeprecatedMessage(String deprecatedMessage) {
+        this.deprecatedMessage = deprecatedMessage;
+    }
+
+    public boolean isDeprecated() {
+        return deprecated;
+    }
+
+    public void setDeprecated(boolean deprecated) {
+        this.deprecated = deprecated;
+    }
+
     public boolean isExistingNameDeprecated() {
         return existingNameDeprecated;
     }

codegen/src/main/java/software/amazon/awssdk/codegen/model/intermediate/MemberModel.java

@@ -55,6 +55,8 @@ public class MemberModel extends DocumentationModel {
     private ParameterHttpMapping http;
 
     private boolean deprecated;
+
+    private String deprecatedMessage;
 
     private ListModel listModel;
 
@@ -301,6 +303,14 @@ public void setDeprecated(boolean deprecated) {
         this.deprecated = deprecated;
     }
 
+    public String getDeprecatedMessage() {
+        return deprecatedMessage;
+    }
+
+    public void setDeprecatedMessage(String deprecatedMessage) {
+        this.deprecatedMessage = deprecatedMessage;
+    }
+
     public boolean isEventPayload() {
         return eventPayload;
     }

codegen/src/main/java/software/amazon/awssdk/codegen/model/intermediate/ShapeModel.java

@@ -37,6 +37,7 @@ public class ShapeModel extends DocumentationModel implements HasDeprecation {
     private String shapeName;
     // the local variable name inside marshaller/unmarshaller implementation
     private boolean deprecated;
+    private String deprecatedMessage;
     private String type;
     private List<String> required;
     private boolean hasPayloadMember;
@@ -94,6 +95,14 @@ public void setDeprecated(boolean deprecated) {
         this.deprecated = deprecated;
     }
 
+    public String getDeprecatedMessage() {
+        return deprecatedMessage;
+    }
+
+    public void setDeprecatedMessage(String deprecatedMessage) {
+        this.deprecatedMessage = deprecatedMessage;
+    }
+
     public String getC2jName() {
         return c2jName;
     }

codegen/src/main/java/software/amazon/awssdk/codegen/model/service/Member.java

@@ -41,6 +41,8 @@ public class Member {
 
     private boolean deprecated;
 
+    private String deprecatedMessage;
+
     private boolean jsonvalue;
 
     private String timestampFormat;
@@ -153,6 +155,14 @@ public void setDeprecated(boolean deprecated) {
         this.deprecated = deprecated;
     }
 
+    public String getDeprecatedMessage() {
+        return deprecatedMessage;
+    }
+
+    public void setDeprecatedMessage(String deprecatedMessage) {
+        this.deprecatedMessage = deprecatedMessage;
+    }
+
     public boolean getJsonvalue() {
         return jsonvalue;
     }

codegen/src/main/java/software/amazon/awssdk/codegen/model/service/Shape.java

@@ -59,6 +59,8 @@ public class Shape {
     private boolean fault;
 
     private boolean deprecated;
+
+    private String deprecatedMessage;
 
     private boolean eventstream;
 
@@ -260,6 +262,14 @@ public void setDeprecated(boolean deprecated) {
         this.deprecated = deprecated;
     }
 
+    public String getDeprecatedMessage() {
+        return deprecatedMessage;
+    }
+
+    public void setDeprecatedMessage(String deprecatedMessage) {
+        this.deprecatedMessage = deprecatedMessage;
+    }
+
     public boolean isEventstream() {
         return eventstream;
     }

codegen/src/main/java/software/amazon/awssdk/codegen/poet/model/AwsServiceModel.java

@@ -18,6 +18,7 @@
 import static javax.lang.model.element.Modifier.FINAL;
 import static javax.lang.model.element.Modifier.PRIVATE;
 import static javax.lang.model.element.Modifier.PUBLIC;
+import static software.amazon.awssdk.codegen.poet.model.DeprecationUtils.checkDeprecated;
 
 import com.squareup.javapoet.ClassName;
 import com.squareup.javapoet.CodeBlock;
@@ -509,7 +510,7 @@ private Stream<MethodSpec> memberGetters(MemberModel member) {
 
         result.add(memberGetter(member));
 
-        return result.stream();
+        return checkDeprecated(member, result).stream();
     }
 
     private boolean shouldGenerateDeprecatedNameGetter(MemberModel member) {

codegen/src/main/java/software/amazon/awssdk/codegen/poet/model/DeprecationUtils.java

@@ -0,0 +1,37 @@
+package software.amazon.awssdk.codegen.poet.model;
+
+import static java.util.stream.Collectors.toList;
+import static software.amazon.awssdk.codegen.internal.Constant.LF;
+
+import com.squareup.javapoet.AnnotationSpec;
+import com.squareup.javapoet.MethodSpec;
+import java.util.List;
+import software.amazon.awssdk.codegen.model.intermediate.MemberModel;
+import software.amazon.awssdk.utils.StringUtils;
+
+public final class DeprecationUtils {
+
+    private static final AnnotationSpec DEPRECATED = AnnotationSpec.builder(Deprecated.class).build();
+
+    /**
+     * If a given member is modeled as deprecated, add the {@link Deprecated} annotation to the method and, if the method
+     * already has existing Javadoc, append a section with the {@code @deprecated} tag.
+     */
+    public static MethodSpec checkDeprecated(MemberModel member, MethodSpec method) {
+        if (!member.isDeprecated() || method.annotations.contains(DEPRECATED)) {
+            return method;
+        }
+        MethodSpec.Builder builder = method.toBuilder().addAnnotation(DEPRECATED);
+        if (!method.javadoc.isEmpty()) {
+            builder.addJavadoc(LF + "@deprecated");
+            if (StringUtils.isNotBlank(member.getDeprecatedMessage())) {
+                builder.addJavadoc("$L", " " + member.getDeprecatedMessage());
+            }
+        }
+        return builder.build();
+    }
+
+    public static List<MethodSpec> checkDeprecated(MemberModel member, List<MethodSpec> methods) {
+        return methods.stream().map(methodSpec -> checkDeprecated(member, methodSpec)).collect(toList());
+    }
+}

codegen/src/main/java/software/amazon/awssdk/codegen/poet/model/ModelBuilderSpecs.java

@@ -16,6 +16,7 @@
 package software.amazon.awssdk.codegen.poet.model;
 
 import static java.util.stream.Collectors.toList;
+import static software.amazon.awssdk.codegen.poet.model.DeprecationUtils.checkDeprecated;
 
 import com.squareup.javapoet.ClassName;
 import com.squareup.javapoet.FieldSpec;
@@ -76,8 +77,10 @@ public TypeSpec builderInterface() {
 
         shapeModel.getNonStreamingMembers()
                   .forEach(m -> {
-                      builder.addMethods(accessorsFactory.fluentSetterDeclarations(m, builderInterfaceName()));
-                      builder.addMethods(accessorsFactory.convenienceSetterDeclarations(m, builderInterfaceName()));
+                      builder.addMethods(
+                          checkDeprecated(m, accessorsFactory.fluentSetterDeclarations(m, builderInterfaceName())));
+                      builder.addMethods(
+                          checkDeprecated(m, accessorsFactory.convenienceSetterDeclarations(m, builderInterfaceName())));
                   });
 
         if (isException()) {
@@ -212,13 +215,10 @@ private List<MethodSpec> accessors() {
         List<MethodSpec> accessors = new ArrayList<>();
         shapeModel.getNonStreamingMembers()
                   .forEach(m -> {
-                      accessors.add(accessorsFactory.beanStyleGetter(m));
-
-                      List<MethodSpec> fluentSetters = accessorsFactory.fluentSetters(m, builderInterfaceName());
-                      accessors.addAll(fluentSetters);
-
-                      accessors.addAll(accessorsFactory.beanStyleSetters(m));
-                      accessors.addAll(accessorsFactory.convenienceSetters(m, builderInterfaceName()));
+                      accessors.add(checkDeprecated(m, accessorsFactory.beanStyleGetter(m)));
+                      accessors.addAll(checkDeprecated(m, accessorsFactory.fluentSetters(m, builderInterfaceName())));
+                      accessors.addAll(checkDeprecated(m, accessorsFactory.beanStyleSetters(m)));
+                      accessors.addAll(checkDeprecated(m, accessorsFactory.convenienceSetters(m, builderInterfaceName())));
                   });
 
         if (isException()) {

codegen/src/test/resources/software/amazon/awssdk/codegen/poet/model/customization.config

@@ -18,6 +18,16 @@
                     }
                 }
             ]
+        },
+        "OperationWithDeprecatedMemberRequest": {
+            "modify": [
+                {
+                    "MemberModifiedAsDeprecated": {
+                        "deprecated": true,
+                        "deprecatedMessage": "This field is modified as deprecated."
+                    }
+                }
+            ]
         }
     },
     "underscoresInNameBehavior": "ALLOW"