software.amazon.awssdk.regions.ServiceMetadata Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of regions Show documentation
There is a newer version: 2.29.15
/*
 * Copyright 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.regions;

import java.net.URI;
import java.util.List;
import java.util.function.Consumer;
import software.amazon.awssdk.annotations.SdkPublicApi;
import software.amazon.awssdk.profiles.ProfileFile;
import software.amazon.awssdk.regions.internal.MetadataLoader;

/**
 * Metadata about a service, like S3, DynamoDB, etc.
 *
 * This is useful for building meta-functionality around AWS services. For example, UIs that list the available regions for a
 * service would use the {@link #regions()} method for a service.
 *
 * This is usually created by calling the {@code serviceMetadata} method on the service client's interface, but can also be
 * created by calling the {@link #of(String)} method and providing the service's unique endpoint prefix.
 */
@SdkPublicApi
public interface ServiceMetadata {
    /**
     * Retrieve the AWS endpoint that should be used for this service in the provided region, if no {@link EndpointTag}s are
     * desired.
     *
     * @param region The region that should be used to load the service endpoint.
     * @return The region-specific endpoint for this service.
     * @throws RuntimeException if an endpoint cannot be determined.
     */
    default URI endpointFor(Region region) {
        return endpointFor(ServiceEndpointKey.builder().region(region).build());
    }

    /**
     * Retrieve the AWS endpoint that should be used for this service associated with the provided {@link ServiceEndpointKey}.
     *
     * @param key The service endpoint key with which an endpoint should be retrieved.
     * @return The region-specific endpoint for this service.
     * @throws RuntimeException if an endpoint cannot be determined.
     */
    default URI endpointFor(ServiceEndpointKey key) {
        throw new UnsupportedOperationException();
    }

    /**
     * Retrieve the region that should be used for message signing when communicating with this service in the provided region.
     * For most services, this will match the provided region, but it may differ for unusual services or when using a region that
     * does not correspond to a physical location, like {@link Region#AWS_GLOBAL}.
     *
     * @param region The region from which the signing region should be derived.
     * @return The region that should be used for signing messages when communicating with this service in the requested region.
     */
    default Region signingRegion(Region region) {
        return signingRegion(ServiceEndpointKey.builder().region(region).build());
    }

    /**
     * Retrieve the region that should be used for message signing when communicating with this service in the provided region
     * and with the provided endpoint tags. For most services, this will match the provided region, but it may differ for
     * unusual services or when using a region that does not correspond to a physical location, like {@link Region#AWS_GLOBAL}.
     *
     * @param key The service endpoint key with which an endpoint should be retrieved.
     * @return The region that should be used for signing messages when communicating with this service in the requested region.
     */
    default Region signingRegion(ServiceEndpointKey key) {
        throw new UnsupportedOperationException();
    }

    /**
     * Retrieve the list of regions this service is currently available in.
     *
     * @return The list of regions this service is currently available in.
     */
    List regions();

    /**
     * Retrieve the service-specific partition configuration of each partition in which this service is currently available.
     *
     * @return The list of service-specific service metadata for each partition in which this service is available.
     */
    List servicePartitions();

    /**
     * Load the service metadata for the provided service endpoint prefix. This should only be used when you do not wish to have
     * a dependency on the service for which you are retrieving the metadata. When you have a dependency on the service client,
     * the metadata should instead be loaded using the service client's {@code serviceMetadata()} method.
     *
     * @param serviceEndpointPrefix The service-specific endpoint prefix of the service about which you wish to load metadata.
     * @return The service metadata for the requested service.
     */
    static ServiceMetadata of(String serviceEndpointPrefix) {
        ServiceMetadata metadata = MetadataLoader.serviceMetadata(serviceEndpointPrefix);
        return metadata == null ? new DefaultServiceMetadata(serviceEndpointPrefix) : metadata;
    }

    /**
     * Reconfigure this service metadata using the provided {@link ServiceMetadataConfiguration}. This is useful, because some
     * service metadata instances refer to external configuration that might wish to be modified, like a {@link ProfileFile}.
     */
    default ServiceMetadata reconfigure(ServiceMetadataConfiguration configuration) {
        return this;
    }

    /**
     * Reconfigure this service metadata using the provided {@link ServiceMetadataConfiguration}. This is useful, because some
     * service metadata instances refer to external configuration that might wish to be modified, like a {@link ProfileFile}.
     *
     * This is a shorthand form of {@link #reconfigure(ServiceMetadataConfiguration)}, without the need to call
     * {@code builder()} or {@code build()}.
     */
    default ServiceMetadata reconfigure(Consumer consumer) {
        ServiceMetadataConfiguration.Builder configuration = ServiceMetadataConfiguration.builder();
        consumer.accept(configuration);
        return reconfigure(configuration.build());
    }
}