1 /*
2 * Copyright 2013-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.regions;
16
17 import java.util.List;
18
19 /**
20 * A collection of metadata about a set of regions and the services they
21 * contain.
22 *
23 * @see RegionUtils
24 */
25 public class RegionMetadata {
26
27 private final RegionMetadataProvider provider;
28
29 /**
30 * Creates a new RegionMetadata object from the given list of regions.
31 *
32 * @param regions the list of regions
33 */
34 public RegionMetadata(final List<Region> regions) {
35 this.provider = new InMemoryRegionsProvider(regions);
36 }
37
38 public RegionMetadata(RegionMetadataProvider provider) {
39 this.provider = provider;
40 }
41
42 /**
43 * Returns an immutable list of all regions known to this region metadata
44 * object, in no particular order.
45 *
46 * @return an immutable list of all regions
47 */
48 public List<Region> getRegions() {
49 return provider.getRegions();
50 }
51
52 /**
53 * Returns the region with the name given, if it exists. Otherwise, returns
54 * null.
55 *
56 * @param name the name of the region to search for
57 * @return the corresponding region, if it exists
58 */
59 public Region getRegion(final String name) {
60 return provider.getRegion(name);
61 }
62
63 /**
64 * Returns a list of the regions that support the service given.
65 *
66 * @param service
67 * The service endpoint prefix which can be retrieved from the
68 * constant ENDPOINT_PREFIX of the specific service client interface,
69 * e.g. AmazonEC2.ENDPOINT_PREFIX.
70 * @return the list of regions with support for the given service
71 */
72 public List<Region> getRegionsForService(final String service) {
73 return provider.getRegionsForService(service);
74 }
75
76 /**
77 * Returns the region associated with the specified endpoint by searching the endpoint configuration for an endpoint
78 * that is explicitly listed. This is likely to be null, because most endpoints are not explicitly listed in the endpoints
79 * file.
80 *
81 * This is mostly useful for retrieving the region of non-standard endpoints that do not include the region in the host name.
82 * These include global endpoints (budgets.amazonaws.com),
83 *
84 * Unlike {@link #getRegionByEndpoint(String)}, this returns null on failure instead of raising an exception.
85 *
86 * @param endpoint The endpoint to look up in the region metadata.
87 * @return The region, or null if it cannot be determined.
88 */
89 public Region tryGetRegionByExplicitEndpoint(String endpoint) {
90 return provider.tryGetRegionByExplicitEndpoint(endpoint);
91 }
92
93 /**
94 * Returns the region associated with the specified endpoint by searching the endpoint configuration for a partition
95 * that matches the DNS suffix of the provided endpoint and extracting the region name based on the endpoint pattern for
96 * that partition. This may be wrong if the service does not follow the endpoint pattern for the partition. This returns
97 * null if the endpoint provided does not appear to include a region, or does not match a known partition DNS suffix.
98 *
99 * Unlike {@link #getRegionByEndpoint(String)}, this returns null on failure instead of raising an exception.
100 *
101 * @param endpoint The endpoint to look up in the region metadata based on the DNS suffix.
102 * @return The region, or null if it cannot be determined.
103 */
104 public Region tryGetRegionByEndpointDnsSuffix(String endpoint) {
105 return provider.tryGetRegionByEndpointDnsSuffix(endpoint);
106 }
107
108 /**
109 * Searches through all known regions to find one with any service at the
110 * specified endpoint. If no region is found with a service at that
111 * endpoint, an exception is thrown.
112 *
113 * @param endpoint The endpoint for any service residing in the desired region.
114 * @return The region containing any service running at the specified
115 * endpoint, otherwise an exception is thrown if no region is found
116 * with a service at the specified endpoint.
117 * @throws IllegalArgumentException If the given URL is malformed, or if the one of the service
118 * URLs on record is malformed.
119 * @deprecated sdk no longer holds the complete endpoint for every service in the region.
120 * It now uses the partition metadata to compute the endpoints dynamically for new regions and services.
121 */
122 @Deprecated
123 public Region getRegionByEndpoint(String endpoint) {
124 return provider.getRegionByEndpoint(endpoint);
125 }
126
127 @Override
128 public String toString() {
129 return provider.toString();
130 }
131 }
132