Suggest customers use a global region for IAM if their calls fail. If usability studies show this is the right route, we should update this to work automatically based on the endpoints.json isRegionalized flag so that other services are included automatically.

Author: millems

aws-core/src/main/java/software/amazon/awssdk/awscore/interceptor/GlobalServiceExecutionInterceptor.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.awscore.interceptor;
+
+import java.net.UnknownHostException;
+import software.amazon.awssdk.auth.AwsExecutionAttributes;
+import software.amazon.awssdk.core.exception.SdkClientException;
+import software.amazon.awssdk.core.interceptor.Context;
+import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
+import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
+
+/**
+ * An interceptor that can be used for global services that will tell the customer when they're using a global service that
+ * doesn't support non-global regions.
+ */
+public class GlobalServiceExecutionInterceptor implements ExecutionInterceptor {
+    @Override
+    public void onExecutionFailure(Context.FailedExecution context, ExecutionAttributes executionAttributes) {
+        if (hasCause(context.exception(), UnknownHostException.class) &&
+            !executionAttributes.getAttribute(AwsExecutionAttributes.AWS_REGION).isGlobalRegion()) {
+            throw new SdkClientException("This is a global service. Consider setting AWS_GLOBAL or another global " +
+                                         "region when creating your client.", context.exception());
+        }
+    }
+
+    private boolean hasCause(Throwable thrown, Class<? extends Throwable> cause) {
+        if (thrown == null) {
+            return false;
+        }
+
+        if (cause.isAssignableFrom(thrown.getClass())) {
+            return true;
+        }
+
+        return hasCause(thrown.getCause(), cause);
+    }
+}

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

@@ -90,14 +90,20 @@ public class CustomizationConfig {
      */
     private boolean skipSmokeTests;
 
+    /**
+     * Exclude the create() method on a client. This is useful for global services that will need a global region configured to
+     * work.
+     */
+    private boolean excludeClientCreateMethod = false;
+
     /**
      * A service name that this service client should share models with. The models and non-request marshallers will be generated
      * into the same directory as the provided service's models.
      */
     private String shareModelsWith;
 
     /**
-     * Expression to return a service specific instance of {@link software.amazon.awssdk.http.SdkHttpConfigurationOptions}. If
+     * Expression to return a service specific instance of {@link software.amazon.awssdk.http.SdkHttpConfigurationOption}. If
      * present, the client builder will override the hook to return service specific HTTP config and inject this expression into
      * that method. At some point we may want to have a more data driven way to declare these settings but right now we don't
      * have any requirements to necessitate that and referencing handwritten code is simpler. See SWF customization.config
@@ -259,6 +265,14 @@ public void setSkipSmokeTests(boolean skipSmokeTests) {
         this.skipSmokeTests = skipSmokeTests;
     }
 
+    public boolean isExcludeClientCreateMethod() {
+        return excludeClientCreateMethod;
+    }
+
+    public void setExcludeClientCreateMethod(boolean excludeClientCreateMethod) {
+        this.excludeClientCreateMethod = excludeClientCreateMethod;
+    }
+
     public String getShareModelsWith() {
         return shareModelsWith;
     }

codegen/src/main/java/software/amazon/awssdk/codegen/poet/client/AsyncClientInterface.java

@@ -68,18 +68,24 @@ public AsyncClientInterface(IntermediateModel model) {
 
     @Override
     public TypeSpec poetSpec() {
-        return PoetUtils.createInterfaceBuilder(className)
-                        .addSuperinterface(SdkClient.class)
-                        .addSuperinterface(SdkAutoCloseable.class)
-                        .addJavadoc(getJavadoc())
-                        .addField(FieldSpec.builder(String.class, "SERVICE_NAME")
-                                           .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
-                                           .initializer("$S", model.getMetadata().getSigningName())
-                                           .build())
-                        .addMethod(create())
-                        .addMethod(builder())
-                        .addMethods(operationsAndSimpleMethods())
-                        .build();
+        TypeSpec.Builder result = PoetUtils.createInterfaceBuilder(className);
+
+        result.addSuperinterface(SdkClient.class)
+              .addSuperinterface(SdkAutoCloseable.class)
+              .addJavadoc(getJavadoc())
+              .addField(FieldSpec.builder(String.class, "SERVICE_NAME")
+                                 .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
+                                 .initializer("$S", model.getMetadata().getSigningName())
+                                 .build());
+
+        if (!model.getCustomizationConfig().isExcludeClientCreateMethod()) {
+            result.addMethod(create());
+        }
+
+        result.addMethod(builder())
+              .addMethods(operationsAndSimpleMethods());
+
+        return result.build();
     }
 
     @Override

codegen/src/main/java/software/amazon/awssdk/codegen/poet/client/SyncClientInterface.java

@@ -68,19 +68,25 @@ public SyncClientInterface(IntermediateModel model) {
 
     @Override
     public TypeSpec poetSpec() {
-        return PoetUtils.createInterfaceBuilder(className)
-                        .addSuperinterface(SdkClient.class)
-                        .addSuperinterface(SdkAutoCloseable.class)
-                        .addJavadoc(getJavadoc())
-                        .addField(FieldSpec.builder(String.class, "SERVICE_NAME")
-                                                           .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
-                                                           .initializer("$S", model.getMetadata().getSigningName())
-                                                           .build())
-                        .addMethod(create())
-                        .addMethod(builder())
-                        .addMethods(operations())
-                        .addMethod(serviceMetadata())
-                        .build();
+        TypeSpec.Builder result = PoetUtils.createInterfaceBuilder(className);
+
+        result.addSuperinterface(SdkClient.class)
+              .addSuperinterface(SdkAutoCloseable.class)
+              .addJavadoc(getJavadoc())
+              .addField(FieldSpec.builder(String.class, "SERVICE_NAME")
+                                 .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
+                                 .initializer("$S", model.getMetadata().getSigningName())
+                                 .build());
+
+        if (!model.getCustomizationConfig().isExcludeClientCreateMethod()) {
+            result.addMethod(create());
+        }
+
+        result.addMethod(builder())
+              .addMethods(operations())
+              .addMethod(serviceMetadata());
+
+        return result.build();
     }
 
     @Override

regions/src/main/java/software/amazon/awssdk/regions/Region.java

@@ -62,20 +62,20 @@ public class Region extends AbstractEnum {
     public static final Region US_WEST_1 = Region.of("us-west-1");
     public static final Region US_WEST_2 = Region.of("us-west-2");
 
-    public static final Region AWS_GLOBAL = Region.of("aws-global");
+    public static final Region AWS_GLOBAL = Region.of("aws-global", true);
 
     // AWS CN Partition Regions
 
     public static final Region CN_NORTH_1 = Region.of("cn-north-1");
     public static final Region CN_NORTHWEST_1 = Region.of("cn-northwest-1");
-    public static final Region AWS_CN_GLOBAL = Region.of("aws-cn-global");
+    public static final Region AWS_CN_GLOBAL = Region.of("aws-cn-global", true);
 
     /**
      * AWS Gov Cloud Partition Regions.
      */
     public static final class GovCloud {
         public static final Region US_GOV_WEST_1 = Region.of("us-gov-west-1");
-        public static final Region AWS_US_GOV_GLOBAL = Region.of("aws-us-gov-global");
+        public static final Region AWS_US_GOV_GLOBAL = Region.of("aws-us-gov-global", true);
 
         public static final List<Region> REGIONS = Collections.unmodifiableList(Arrays.asList(
                 US_GOV_WEST_1,
@@ -110,8 +110,11 @@ public static List<Region> getRegions() {
             CN_NORTHWEST_1,
             AWS_CN_GLOBAL));
 
-    private Region(String value) {
+    private final boolean isGlobalRegion;
+
+    private Region(String value, boolean isGlobalRegion) {
         super(value);
+        this.isGlobalRegion = isGlobalRegion;
     }
 
     /**
@@ -125,8 +128,12 @@ private Region(String value) {
      * @return The region associated with the provided name.
      */
     public static Region of(String value) {
+        return of(value, false);
+    }
+
+    private static Region of(String value, boolean isGlobalRegion) {
         Validate.paramNotBlank(value, "region");
-        return AbstractEnum.value(value, Region.class, Region::new);
+        return AbstractEnum.value(value, Region.class, v -> new Region(v, isGlobalRegion));
     }
 
     /**
@@ -136,4 +143,7 @@ public static List<Region> getRegions() {
         return REGIONS;
     }
 
+    public boolean isGlobalRegion() {
+        return isGlobalRegion;
+    }
 }

services/iam/src/main/resources/codegen-resources/customization.config

@@ -16,5 +16,6 @@
         "listSigningCertificates",
         "listAccessKeys"
     ],
-    "blacklistedSimpleMethods" : ["updateAccountPasswordPolicy"]
+    "blacklistedSimpleMethods" : ["updateAccountPasswordPolicy"],
+    "excludeClientCreateMethod": true
 }

services/iam/src/main/resources/software/amazon/awssdk/services/iam/execution.interceptors

@@ -0,0 +1 @@
+software.amazon.awssdk.awscore.interceptor.GlobalServiceExecutionInterceptor