001package com.nimbusds.infinispan.persistence.dynamodb; 002 003 004import com.amazonaws.services.dynamodbv2.document.Item; 005 006import com.nimbusds.infinispan.persistence.common.InfinispanEntry; 007import com.nimbusds.infinispan.persistence.dynamodb.config.DynamoDBStoreConfiguration; 008 009 010/** 011 * Interface for transforming between Infinispan entries (key / value pair and 012 * metadata) and a corresponding DynamoDB item. Implementations must be 013 * thread-safe. 014 * 015 * <p>To specify an entry transformer for a given Infinispan cache that is 016 * backed by a DynamoDB store, provide its class name to the 017 * {@link DynamoDBStoreConfiguration store configuration}. 018 */ 019public interface DynamoDBItemTransformer<K,V> { 020 021 022 /** 023 * Initialisation context. 024 */ 025 interface InitContext { 026 027 028 /** 029 * Checks if automatic item expiration is enabled for the 030 * DynamoDB table. The item transformer should then specify 031 * a {@link #getHashKeyAttributeName() TTL attribute name} and 032 * populate it for items that are to be expired automatically 033 * by DynamoDB. 034 * 035 * @return {@code true} if automatic item expiration is 036 * enabled. 037 */ 038 boolean isEnableTTL(); 039 } 040 041 042 /** 043 * Provides initialisation. 044 * 045 * @param initContext The initialisation context. 046 */ 047 default void init(final InitContext initContext) { } 048 049 050 /** 051 * Returns the base name of the DynamoDB table. Required to create and 052 * to connect to the DynamoDB table for storing the cache entries. The 053 * final DynamoDB table name is formed by prefixing the optional 054 * configuration {@code table-prefix} to the base name. 055 * 056 * @return The table name. 057 */ 058 String getTableName(); 059 060 061 /** 062 * Returns the DynamoDB hash key attribute name. Required to create the 063 * DynamoDB table for storing the cache entries. 064 * 065 * @return The hash key attribute name. 066 */ 067 String getHashKeyAttributeName(); 068 069 070 /** 071 * Returns the optional DynamoDB range key attribute name. Required to 072 * create the DynamoDB table for storing the cache entries. 073 * 074 * @return The range key attribute name, {@code null} if none. 075 */ 076 default String getRangeKeyAttributeName() { 077 return null; 078 } 079 080 081 /** 082 * Returns the optional DynamoDB time-to-live attribute name. Required 083 * to create the DynamoDB table for the storing the cache entries with 084 * DynamoDB managed expiration. 085 * 086 * @return The TTL attribute name, {@code null} if none. 087 */ 088 default String getTTLAttributeName() { 089 return null; 090 } 091 092 093 /** 094 * Resolves the DynamoDB hash key value (of scalar attribute type 095 * string) for the specified Infinispan entry key. 096 * 097 * <p>Use {@link #resolvePrimaryKey(Object)} instead. 098 * 099 * @param key The Infinispan entry key. Not {@code null}. 100 * 101 * @return The DynamoDB hash key value. 102 */ 103 @Deprecated 104 String resolveHashKey(final K key); 105 106 107 /** 108 * Resolves the DynamoDB primary key (hash key value of scalar 109 * attribute type string, with optional additional range key value) for 110 * the specified Infinispan entry key. 111 * 112 * @param key The Infinispan entry key. Not {@code null}. 113 * 114 * @return The DynamoDB primary key value. 115 */ 116 default PrimaryKeyValue resolvePrimaryKey(final K key) { 117 return new PrimaryKeyValue(resolveHashKey(key), null); 118 } 119 120 121 /** 122 * Transforms the specified Infinispan entry (key / value pair with 123 * optional metadata) to a DynamoDB item. 124 * 125 * <p>Example: 126 * 127 * <p>Infinispan entry: 128 * 129 * <ul> 130 * <li>Key: cae7t 131 * <li>Value: Java POJO with fields {@code uid=cae7t}, 132 * {@code givenName=Alice}, {@code surname=Adams} and 133 * {@code [email protected]}. 134 * <li>Metadata: Specifies the entry expiration and other 135 * properties. 136 * </ul> 137 * 138 * <p>Resulting DynamoDB item: 139 * 140 * <pre> 141 * uid: cae7t (key) 142 * surname: Adams 143 * given_name: Alice 144 * email: [email protected] 145 * </pre> 146 * 147 * @param infinispanEntry The Infinispan entry. Not {@code null}. 148 * 149 * @return The DynamoDB item. 150 */ 151 Item toItem(final InfinispanEntry<K,V> infinispanEntry); 152 153 154 /** 155 * Transforms the specified DynamoDB item to an Infinispan entry (key / 156 * value / metadata triple). 157 * 158 * <p>Example: 159 * 160 * <p>DynamoDB item: 161 * 162 * <pre> 163 * uid: cae7t 164 * surname: Adams 165 * given_name: Alice 166 * email: [email protected] 167 * </pre> 168 * 169 * <p>Resulting Infinispan entry: 170 * 171 * <ul> 172 * <li>Key: cae7t 173 * <li>Value: Java POJO with fields {@code uid=cae7t}, 174 * {@code givenName=Alice}, {@code surname=Adams} and 175 * {@code [email protected]}. 176 * <li>Metadata: Default metadata (no expiration, etc). 177 * </ul> 178 * 179 * @param item The DynamoDB item. Must not be {@code null}. 180 * 181 * @return The Infinispan entry (key / value pair with optional 182 * metadata). 183 */ 184 InfinispanEntry<K,V> toInfinispanEntry(final Item item); 185}