1 /*
2 * Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License").
5 * You may not use this file except in compliance with the License.
6 * A copy of the License is located at
7 *
8 * http://aws.amazon.com/apache2.0
9 *
10 * or in the "license" file accompanying this file. This file is distributed
11 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12 * express or implied. See the License for the specific language governing
13 * permissions and limitations under the License.
14 */
15 package com.amazonaws.services.s3.model;
16
17 import com.amazonaws.regions.RegionUtils;
18 import com.amazonaws.services.s3.AmazonS3Client;
19
20 import java.util.Arrays;
21 import java.util.List;
22 import java.util.regex.Pattern;
23
24
25 /**
26 * Specifies constants that define Amazon S3 Regions.
27 * <p>
28 * Amazon S3 Regions allow the user to choose the geographical region where Amazon S3
29 * will store the buckets the user creates. Choose a Amazon S3 Region to optimize
30 * latency, minimize costs, or address regulatory requirements.
31 * </p>
32 * <p>
33 * Objects stored in a Amazon S3 Region never leave that region unless explicitly
34 * transferred to another region.
35 * </p>
36 * <p>
37 * In Amazon S3, all the regions provides
38 * read-after-write consistency for PUTS of new objects in Amazon
39 * S3 buckets and eventual consistency for overwrite PUTS and DELETES.
40 * </p>
41 */
42 public enum Region {
43
44 /**
45 * The US Standard Amazon S3 Region. This region is equivalent to 'us-east-1', see
46 * <a href="https://aws.amazon.com/s3/faqs/">Amazon Simple Storage Service (S3) FAQs</a> for more information.
47 * <p>
48 * This is the default Amazon S3 Region. All requests sent to <code>s3.amazonaws.com</code> go
49 * to this region unless a location constraint is specified when creating a bucket.
50 */
51 US_Standard((String[]) null),
52
53 /**
54 * The US-East-2 (Ohio) Region. This region
55 * uses Amazon S3 servers located in Ohio.
56 * <p>
57 * When using buckets in this region, set the client
58 * endpoint to <code>s3.us-east-2.amazonaws.com</code> on all requests to these buckets
59 * to reduce any latency experienced after the first hour of
60 * creating a bucket in this region.
61 * </p>
62 */
63 US_East_2("us-east-2"),
64
65 /**
66 * The US-West (Northern California) Amazon S3 Region. This region uses Amazon S3
67 * servers located in Northern California.
68 * <p>
69 * When using buckets in this region, set the client
70 * endpoint to <code>s3-us-west-1.amazonaws.com</code> on all requests to these
71 * buckets to reduce any latency experienced after the first
72 * hour of creating a bucket in this region.
73 * </p>
74 */
75 US_West("us-west-1"),
76
77 /**
78 * The US-West-2 (Oregon) Region. This region uses Amazon S3 servers located
79 * in Oregon.
80 * <p>
81 * When using buckets in this region, set the client
82 * endpoint to <code>s3-us-west-2.amazonaws.com</code> on all requests to these buckets
83 * to reduce any latency experienced after the first hour of
84 * creating a bucket in this region.
85 * </p>
86 */
87 US_West_2("us-west-2"),
88
89 /**
90 * The US GovCloud Region. This region uses Amazon S3 servers located in the Northwestern
91 * region of the United States.
92 */
93 US_GovCloud("us-gov-west-1"),
94
95 /**
96 * The US GovCloud (East) Region.
97 */
98 US_Gov_East_1("us-gov-east-1", "AWS GovCloud (US-East)"),
99
100 /**
101 * The EU (Ireland) Amazon S3 Region. This region uses Amazon S3 servers located
102 * in Ireland.
103 */
104 EU_Ireland("eu-west-1","EU"),
105
106 /**
107 * The EU (London) Amazon S3 Region. This region uses Amazon S3 servers located
108 * in London.
109 */
110 EU_London("eu-west-2"),
111
112 /**
113 * The EU (Paris) Amazon S3 Region. This region uses Amazon S3 servers located
114 * in Paris.
115 */
116 EU_Paris("eu-west-3"),
117
118 /**
119 * The EU (Frankfurt) Amazon S3 Region. This region uses Amazon S3 servers
120 * located in Frankfurt.
121 * <p>
122 * The EU (Frankfurt) Region requires AWS V4 authentication, therefore when
123 * accessing buckets inside this region, you need to explicitly configure
124 * the "eu-central-1" endpoint for the AmazonS3Client in order to enable V4
125 * signing:
126 *
127 * <pre>
128 * AmazonS3Client s3 = new AmazonS3Client();
129 * s3.setRegion(RegionUtils.getRegion("eu-central-1"));
130 * </pre>
131 *
132 * </p>
133 *
134 * @see AmazonS3Client#setEndpoint(String)
135 * @see AmazonS3Client#setRegion(com.amazonaws.regions.Region)
136 */
137 EU_Frankfurt("eu-central-1"),
138
139 /**
140 * The EU (Stockholm) Amazon S3 Region. This region uses Amazon S3 servers
141 * located in Stockholm.
142 * <p>
143 * The EU (Stockholm) Region requires AWS V4 authentication, therefore when
144 * accessing buckets inside this region, you need to explicitly configure
145 * the "eu-north-1" endpoint for the AmazonS3Client in order to enable V4
146 * signing:
147 *
148 * <pre>
149 * AmazonS3Client s3 = new AmazonS3Client();
150 * s3.setRegion(RegionUtils.getRegion("eu-north-1"));
151 * </pre>
152 *
153 * </p>
154 *
155 * @see AmazonS3Client#setEndpoint(String)
156 * @see AmazonS3Client#setRegion(com.amazonaws.regions.Region)
157 */
158 EU_North_1("eu-north-1"),
159
160 /**
161 * The EU (Milan) Amazon S3 Region. This region uses Amazon S3 servers
162 * located in Milan.
163 * <p>
164 * The EU (Milan) Region requires AWS V4 authentication, therefore when
165 * accessing buckets inside this region, you need to explicitly configure
166 * the "eu-south-1" endpoint for the AmazonS3Client in order to enable V4
167 * signing:
168 *
169 * <pre>
170 * AmazonS3Client s3 = new AmazonS3Client();
171 * s3.setRegion(RegionUtils.getRegion("eu-south-1"));
172 * </pre>
173 *
174 * </p>
175 *
176 * @see AmazonS3Client#setEndpoint(String)
177 * @see AmazonS3Client#setRegion(com.amazonaws.regions.Region)
178 */
179 EU_South_1("eu-south-1"),
180
181 /**
182 * The Asia Pacific (Hong Kong) Region. This region uses Amazon S3 servers located
183 * in Hong Kong.
184 * <p>
185 * When using buckets in this region, set the client
186 * endpoint to <code>s3.ap-east-1.amazonaws.com</code> on all requests to these buckets
187 * to reduce any latency experienced after the first hour of
188 * creating a bucket in this region.
189 * </p>
190 */
191 AP_HongKong("ap-east-1"),
192
193 /**
194 * The Asia Pacific (Singapore) Region. This region uses Amazon S3 servers located
195 * in Singapore.
196 * <p>
197 * When using buckets in this region, set the client
198 * endpoint to <code>s3-ap-southeast-1.amazonaws.com</code> on all requests to these buckets
199 * to reduce any latency experienced after the first hour of
200 * creating a bucket in this region.
201 * </p>
202 */
203 AP_Singapore("ap-southeast-1"),
204
205 /**
206 * The Asia Pacific (Sydney) Region. This region uses Amazon S3 servers
207 * located in Sydney, Australia.
208 * <p>
209 * When using buckets in this region, set the client endpoint to
210 * <code>s3-ap-southeast-2.amazonaws.com</code> on all requests to these buckets
211 * to reduce any latency experienced after the first hour of creating a
212 * bucket in this region.
213 * </p>
214 */
215 AP_Sydney("ap-southeast-2"),
216
217 /**
218 * The Asia Pacific (Tokyo) Region. This region uses Amazon S3 servers
219 * located in Tokyo.
220 * <p>
221 * When using buckets in this region, set the client endpoint to
222 * <code>s3-ap-northeast-1.amazonaws.com</code> on all requests to these
223 * buckets to reduce any latency experienced after the first hour of
224 * creating a bucket in this region.
225 * </p>
226 */
227 AP_Tokyo("ap-northeast-1"),
228
229 /**
230 * The Asia Pacific (Seoul) Region. This region uses Amazon S3 servers
231 * located in Seoul.
232 * <p>
233 * When using buckets in this region, set the client endpoint to
234 * <code>s3.ap-northeast-2.amazonaws.com</code> on all requests to these
235 * buckets to reduce any latency experienced after the first hour of
236 * creating a bucket in this region.
237 * </p>
238 */
239 AP_Seoul("ap-northeast-2"),
240
241 /**
242 * The Asia Pacific (Mumbai) Region. This region uses Amazon S3 servers
243 * located in Mumbai.
244 * <p>
245 * When using buckets in this region, set the client endpoint to
246 * <code>s3.ap-south-1.amazonaws.com</code> on all requests to these
247 * buckets to reduce any latency experienced after the first hour of
248 * creating a bucket in this region.
249 * </p>
250 */
251 AP_Mumbai("ap-south-1"),
252
253 /**
254 * The South America (Sao Paulo) Region. This region uses Amazon S3 servers
255 * located in Sao Paulo.
256 * <p>
257 * When using buckets in this region, set the client endpoint to
258 * <code>s3-sa-east-1.amazonaws.com</code> on all requests to these buckets
259 * to reduce any latency experienced after the first hour of creating a
260 * bucket in this region.
261 * </p>
262 */
263 SA_SaoPaulo("sa-east-1"),
264
265 /**
266 * The Canada (Central) Region. This region uses Amazon S3 servers
267 * located in Canada.
268 * <p>
269 * When using buckets in this region, set the client endpoint to
270 * <code>s3.ca-central-1.amazonaws.com</code> on all requests to these buckets
271 * to reduce any latency experienced after the first hour of creating a
272 * bucket in this region.
273 * </p>
274 */
275 CA_Central("ca-central-1"),
276
277 /**
278 * The China (Beijing) Region. This region uses Amazon S3 servers
279 * located in Beijing.
280 * <p>
281 * When using buckets in this region, you must set the client endpoint to
282 * <code>s3.cn-north-1.amazonaws.com.cn</code>.
283 * </p>
284 */
285 CN_Beijing("cn-north-1"),
286
287 /**
288 * The China (Ningxia) Region. This region uses Amazon S3 servers
289 * located in Ningxia.
290 * <p>
291 * When using buckets in this region, you must set the client endpoint to
292 * <code>s3.cn-northwest-1.amazonaws.com.cn</code>.
293 * </p>
294 */
295 CN_Northwest_1("cn-northwest-1"),
296
297 /**
298 * The Middle East (Bahrain) Region. This region uses Amazon S3 servers
299 * located in Bahrain.
300 * <p>
301 * When using buckets in this region, you must set the client endpoint to
302 * <code>s3.me-south-1.amazonaws.com</code>.
303 * </p>
304 */
305 ME_Bahrain("me-south-1"),
306
307 /**
308 * The Africa South (Cape Town) Region. This region uses Amazon S3 servers
309 * located in Cape Town.
310 * <p>
311 * When using buckets in this region, you must set the client endpoint to
312 * <code>s3.af-south-1.amazonaws.com</code>.
313 * </p>
314 */
315 AF_CapeTown("af-south-1")
316 ;
317
318 /**
319 * Used to extract the S3 regional id from an S3 end point.
320 * Note this pattern will not match the S3 US standard endpoint by intent.
321 * Exampless:
322 * <pre>
323 * s3-eu-west-1.amazonaws.com
324 * s3.cn-north-1.amazonaws.com.cn
325 * </pre>
326 */
327 public static final Pattern S3_REGIONAL_ENDPOINT_PATTERN =
328 Pattern.compile("s3[-.]([^.]+)\\.amazonaws\\.com(\\.[^.]*)?");
329
330 /** The list of ID's representing each region. */
331 private final List<String> regionIds;
332
333 /**
334 * Constructs a new region with the specified region ID's.
335 *
336 * @param regionIds
337 * The list of ID's representing the S3 region.
338 */
339 private Region(String... regionIds) {
340 this.regionIds = regionIds != null ? Arrays.asList(regionIds) : null;
341 }
342
343 /*
344 * (non-Javadoc)
345 *
346 * @see java.lang.Enum#toString()
347 */
348 @Override
349 public String toString() {
350 return getFirstRegionId0();
351 }
352
353 /**
354 * Returns the first region id or null for {@link #US_Standard}.
355 */
356 public String getFirstRegionId() {
357 return getFirstRegionId0();
358 }
359
360 private String getFirstRegionId0() {
361 return this.regionIds == null || regionIds.size() == 0
362 ? null : this.regionIds.get(0);
363 }
364
365 /**
366 * Returns the Amazon S3 Region enumeration value representing the specified Amazon
367 * S3 Region ID string. If specified string doesn't map to a known Amazon S3
368 * Region, then an <code>IllegalArgumentException</code> is thrown.
369 *
370 * @param s3RegionId
371 * The Amazon S3 region ID string.
372 *
373 * @return The Amazon S3 Region enumeration value representing the specified Amazon
374 * S3 Region ID.
375 *
376 * @throws IllegalArgumentException
377 * If the specified value does not map to one of the known
378 * Amazon S3 regions.
379 */
380 public static Region fromValue(final String s3RegionId) throws IllegalArgumentException
381 {
382 if (s3RegionId == null || s3RegionId.equals("US") || s3RegionId.equals("us-east-1")) {
383 return Region.US_Standard;
384 }
385 for (Region region : Region.values()) {
386 List<String> regionIds = region.regionIds;
387 if (regionIds != null && regionIds.contains(s3RegionId))
388 return region;
389 }
390
391 throw new IllegalArgumentException(
392 "Cannot create enum from " + s3RegionId + " value!");
393 }
394
395 /**
396 * Returns the respective AWS region.
397 */
398 public com.amazonaws.regions.Region toAWSRegion() {
399 String s3regionId = getFirstRegionId();
400 if ( s3regionId == null ) { // US Standard
401 // TODO This is a bit of a hack but customers are relying on this returning us-east-1 rather then
402 // aws-global. For now we'll keep the legacy behavior and consider changing it in the next major version
403 // bump. See TT0073140598
404 return RegionUtils.getRegion("us-east-1");
405 } else {
406 return RegionUtils.getRegion(s3regionId);
407 }
408 }
409 }
410