software.amazon.awssdk.enhanced.dynamodb.TableMetadata Maven / Gradle / Ivy
/*
* 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.enhanced.dynamodb;
import java.util.Collection;
import java.util.Map;
import java.util.Optional;
import software.amazon.awssdk.annotations.SdkPublicApi;
import software.amazon.awssdk.annotations.ThreadSafe;
import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;
/**
* Interface for an object the stores structural information about a DynamoDb table.
*/
@SdkPublicApi
@ThreadSafe
public interface TableMetadata {
/**
* Returns the attribute name of the partition key for an index.
*
* @param indexName The name of the index.
* @return The attribute name representing the partition key for this index.
* @throws IllegalArgumentException if the index does not exist in the metadata or does not have a partition key
* associated with it..
*/
String indexPartitionKey(String indexName);
/**
* Returns the attribute name of the sort key for an index.
*
* @param indexName The name of the index.
* @return Optional of the attribute name representing the sort key for this index; empty if the index does not
* have a sort key.
*/
Optional indexSortKey(String indexName);
/**
* Returns a custom metadata object. These objects are used by extensions to the library, therefore the type of
* object stored is flexible and does not need to be known by the interface.
*
* @param key A unique key for the metadata object. This namespace is shared by all extensions, so it is
* recommended best practice to qualify it with the name of your extension.
* @param objectClass The java class that the object will be cast to before returning. An exception will be
* thrown if the stored object cannot be cast to this class.
* @param The flexible type for the object being returned. The compiler will typically infer this.
* @return An optional containing custom metadata object or empty if the object was not found.
*/
Optional customMetadataObject(String key, Class objectClass);
/**
* Returns all the names of attributes associated with the keys of a specified index.
*
* @param indexName The name of the index.
* @return A collection of all key attribute names for that index.
*/
Collection indexKeys(String indexName);
/**
* Returns all the names of attributes associated with any index (primary or secondary) known for this table.
* Additionally any additional attributes that are deemed to be 'key-like' in how they should be treated will
* also be returned. An example of a 'key-like' attribute that is not actually a key is one tagged as a 'version'
* attribute when using the versioned record extension.
*
* @return A collection of all key attribute names for the table.
*
* @deprecated Use {@link #keyAttributes()} instead.
*/
@Deprecated
Collection allKeys();
/**
* Returns metadata about all the known indices for this table.
* @return A collection of {@link IndexMetadata} containing information about the indices.
*/
Collection indices();
/**
* Returns all custom metadata for this table. These entries are used by extensions to the library, therefore the
* value type of each metadata object stored in the map is not known and is provided as {@link Object}.
*
* This method should not be used to inspect individual custom metadata objects, instead use
* {@link TableMetadata#customMetadataObject(String, Class)} ()} as that will perform a type-safety check on the
* retrieved object.
* @return A map of all the custom metadata for this table.
*/
Map customMetadata();
/**
* Returns metadata about all the known 'key' attributes for this table, such as primary and secondary index keys,
* or any other attribute that forms part of the structure of the table.
* @return A collection of {@link KeyAttributeMetadata} containing information about the keys.
*/
Collection keyAttributes();
/**
* Returns the DynamoDb scalar attribute type associated with a key attribute if one is applicable.
* @param keyAttribute The key attribute name to return the scalar attribute type of.
* @return Optional {@link ScalarAttributeType} of the attribute, or empty if attribute is a non-scalar type.
* @throws IllegalArgumentException if the keyAttribute is not found.
*/
Optional scalarAttributeType(String keyAttribute);
/**
* Returns the attribute name used as the primary partition key for the table.
*
* @return The primary partition key attribute name.
* @throws IllegalArgumentException if the primary partition key is not known.
*/
default String primaryPartitionKey() {
return indexPartitionKey(primaryIndexName());
}
/**
* Returns the attribute name used as the primary sort key for the table.
*
* @return An optional of the primary sort key attribute name; empty if this key is not known.
*/
default Optional primarySortKey() {
return indexSortKey(primaryIndexName());
}
/**
* Returns the names of the attributes that make up the primary key for the table.
*
* @return A collection of attribute names that make up the primary key for the table.
*/
default Collection primaryKeys() {
return indexKeys(primaryIndexName());
}
/**
* Returns an arbitrary constant that should be used as the primary index name. This pattern creates a
* common abstraction and simplifies the implementation of operations that also work on secondary indices such as
* scan() and query().
*
* @return An arbitrary constant that internally represents the primary index name.
*/
static String primaryIndexName() {
// Must include illegal symbols that cannot be used by a real index.
// This value is arbitrary and ephemeral but could end up being serialized with TableMetadata through the
// actions of a client, so it should not be altered unless absolutely necessary.
return "$PRIMARY_INDEX";
}
}