Annotazioni Java per DynamoDB

In questa sezione vengono descritte le annotazioni disponibili per la mappatura delle classi e delle proprietà alle tabelle e agli attributi in Amazon DynamoDB.

Per la documentazione Javadoc corrispondente, consulta Riepilogo dei tipi di annotazioni nella Documentazione di riferimento delle API di AWS SDK for Java.

Nota

Nelle seguenti annotazioni, sono obbligatori solo DynamoDBTable e DynamoDBHashKey.

DynamoDBAttribute

Mappa una proprietà all'attributo della tabella. Per impostazione predefinita, ogni proprietà di classe si mappa a un attributo item con lo stesso nome. Tuttavia, se i nomi non sono gli stessi, puoi utilizzare questa annotazione per mappare una proprietà all'attributo. Nel frammento Java seguente, DynamoDBAttribute mappa la proprietà BookAuthors al nome di attributo Authors della tabella.

@DynamoDBAttribute(attributeName = "Authors")
public List<String> getBookAuthors() { return BookAuthors; }
public void setBookAuthors(List<String> BookAuthors) { this.BookAuthors = BookAuthors; }

DynamoDBMapper utilizza Authors come nome di attributo quando salva l'oggetto nella tabella.

DynamoDB AutoGeneratedKey

Contrassegna una proprietà di chiave di partizione o di ordinamento come generata automaticamente. DynamoDBMapper genera un UUID casuale durante il salvataggio di questi attributi. Solo le proprietà String possono essere contrassegnate come chiavi generate automaticamente.

L'esempio seguente illustra l'utilizzo delle chiavi generate automaticamente.

@DynamoDBTable(tableName="AutoGeneratedKeysExample")
public class AutoGeneratedKeys {
    private String id;
    private String payload;

    @DynamoDBHashKey(attributeName = "Id")
    @DynamoDBAutoGeneratedKey
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }

    @DynamoDBAttribute(attributeName="payload")
    public String getPayload() { return this.payload; }
    public void setPayload(String payload) { this.payload = payload; }

    public static void saveItem() {
        AutoGeneratedKeys obj = new AutoGeneratedKeys();
        obj.setPayload("abc123");

        // id field is null at this point
        DynamoDBMapper mapper = new DynamoDBMapper(dynamoDBClient);
        mapper.save(obj);

        System.out.println("Object was saved with id " + obj.getId());
    }
}

DynamoDB AutoGeneratedTimestamp

Genera automaticamente un timestamp.

@DynamoDBAutoGeneratedTimestamp(strategy=DynamoDBAutoGenerateStrategy.ALWAYS)
public Date getLastUpdatedDate() { return lastUpdatedDate; }
public void setLastUpdatedDate(Date lastUpdatedDate) { this.lastUpdatedDate = lastUpdatedDate; }

Facoltativamente, la strategia di generazione automatica può essere definita fornendo un attributo di strategia. Il valore predefinito è ALWAYS.

DynamoDBDocument

Indica che una classe può essere serializzata come un documento di Amazon DynamoDB.

Ad esempio, si supponga di voler mappare un documento JSON a un attributo DynamoDB di tipo Map (M). Il seguente esempio di codice definisce un item contenente un attributo nidificato (Pictures) di tipo Map.

public class ProductCatalogItem {

    private Integer id;  //partition key
    private Pictures pictures;
    /* ...other attributes omitted... */

    @DynamoDBHashKey(attributeName="Id")
    public Integer getId() { return id;}
    public void setId(Integer id) {this.id = id;}

    @DynamoDBAttribute(attributeName="Pictures")
    public Pictures getPictures() { return pictures;}
    public void setPictures(Pictures pictures) {this.pictures = pictures;}

    // Additional properties go here.

    @DynamoDBDocument
    public static class Pictures {
        private String frontView;
        private String rearView;
        private String sideView;

        @DynamoDBAttribute(attributeName = "FrontView")
        public String getFrontView() { return frontView; }
        public void setFrontView(String frontView) { this.frontView = frontView; }

        @DynamoDBAttribute(attributeName = "RearView")
        public String getRearView() { return rearView; }
        public void setRearView(String rearView) { this.rearView = rearView; }

        @DynamoDBAttribute(attributeName = "SideView")
        public String getSideView() { return sideView; }
        public void setSideView(String sideView) { this.sideView = sideView; }

     }
}

Puoi quindi salvare un nuovo item ProductCatalog, con Pictures, come mostrato nell'esempio seguente.

ProductCatalogItem item = new ProductCatalogItem();

Pictures pix = new Pictures();
pix.setFrontView("http://example.com/products/123_front.jpg");
pix.setRearView("http://example.com/products/123_rear.jpg");
pix.setSideView("http://example.com/products/123_left_side.jpg");
item.setPictures(pix);

item.setId(123);

mapper.save(item); 

L'aspetto dell'item ProductCatalog risultante dovrebbe essere simile al seguente (in formato JSON).

{
  "Id" : 123
  "Pictures" : {
    "SideView" : "http://example.com/products/123_left_side.jpg",
    "RearView" : "http://example.com/products/123_rear.jpg",
    "FrontView" : "http://example.com/products/123_front.jpg"
  }
} 

DynamoDB HashKey

Mappa una proprietà di classe alla chiave di partizione della tabella. La proprietà deve essere uno dei tipi di stringa, numero o binario scalari. La proprietà non può essere un tipo di raccolta.

Supponi di avere una tabella, ProductCatalog, che abbia come chiave primaria l'Id. Il seguente codice Java definisce una classe CatalogItem e mappa la sua proprietà Id alla chiave primaria della tabella ProductCatalog utilizzando il tag @DynamoDBHashKey.

@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {
    private Integer Id;
   @DynamoDBHashKey(attributeName="Id")
   public Integer getId() {
        return Id;
   }
   public void setId(Integer Id) {
        this.Id = Id;
   }
   // Additional properties go here.
}

DynamoDBIgnore

Indica all'istanza DynamoDBMapper che la proprietà associata deve essere ignorata. Quando salvi i dati nella tabella, DynamoDBMapper non salva questa proprietà nella tabella.

Applicato al metodo getter o al campo della classe per una proprietà non modellata. Se l'annotazione viene applicata direttamente al campo della classe, il getter e il setter corrispondenti devono essere dichiarati nella stessa classe.

DynamoDB IndexHashKey

Mappa una proprietà di classe alla chiave di partizione di un indice secondario globale. La proprietà deve essere uno dei tipi di stringa, numero o binario scalari. La proprietà non può essere un tipo di raccolta.

Utilizza questa annotazione se è necessario eseguire una Query su un indice secondario globale. È necessario specificare il nome dell'indice (globalSecondaryIndexName). Se il nome della proprietà di classe è diverso dalla chiave di partizione dell'indice, è necessario inoltre specificare il nome di tale attributo dell'indice (attributeName).

DynamoDB IndexRangeKey

Associa una proprietà di classe alla chiave di ordinamento di un indice secondario globale o di un indice secondario locale. La proprietà deve essere uno dei tipi di stringa, numero o binario scalari. La proprietà non può essere un tipo di raccolta.

Utilizza questa annotazione se è necessario eseguire una Query su un indice secondario locale o globale e si desidera rifinire i risultati utilizzando la chiave di ordinamento dell'indice. È necessario specificare il nome dell'indice (globalSecondaryIndexName, oppure localSecondaryIndexName). Se il nome della proprietà di classe è diverso dalla chiave di ordinamento dell'indice, è necessario inoltre specificare il nome di tale attributo dell'indice (attributeName).

DynamoDB RangeKey

Mappa una proprietà di classe alla chiave di ordinamento della tabella. La proprietà deve essere uno dei tipi di stringa, numero o binario scalari. Non può essere un tipo di raccolta.

Se la chiave primaria è composita (chiave di partizione e chiave di ordinamento), puoi utilizzare questo tag per mappare il campo della classe alla chiave di ordinamento. Ad esempio, supponiamo che tu abbia una tabella Reply in cui vengono memorizzate le risposte dei thread di un forum. Ogni thread può contenere molte risposte. Pertanto, la chiave primaria di questa tabella è sia ThreadId sia ReplyDateTime. La chiave di partizione è ThreadId e la chiave di ordinamento è ReplyDateTime.

Il seguente codice Java definisce una classe Reply e la mappa alla tabella Reply. Esso utilizza sia il tag @DynamoDBHashKey che @DynamoDBRangeKey per identificare le proprietà di classe che si mappano alla chiave primaria.

@DynamoDBTable(tableName="Reply")
public class Reply {
    private Integer id;
    private String replyDateTime;

    @DynamoDBHashKey(attributeName="Id")
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }

    @DynamoDBRangeKey(attributeName="ReplyDateTime")
    public String getReplyDateTime() { return replyDateTime; }
    public void setReplyDateTime(String replyDateTime) { this.replyDateTime = replyDateTime; }

   // Additional properties go here.
}

DynamoDBTable

Identifica la tabella di destinazione di DynamoDB. Ad esempio, il seguente codice Java definisce una classe Developer e la mappa alla tabella People in DynamoDB.

@DynamoDBTable(tableName="People")
public class Developer { ...} 

L'annotazione @DynamoDBTable può essere ereditata. Tutte le nuove classi che ereditano dalla classe Developer vengono pure mappate alla tabella People. Ad esempio, supponiamo che tu abbia creato una classe Lead che erediti dalla classe Developer. Poiché hai mappato la classe Developer alla tabella People, anche gli oggetti della classe Lead vengono memorizzati nella stessa tabella.

@DynamoDBTable può anche essere sovrascritto. Tutte le nuove classi che ereditano dalla classe Developer vengono mappate alla stessa tabella People per impostazione predefinita. Tuttavia, puoi sovrascrivere questa mappatura predefinita. Ad esempio, se crei una classe che eredita dalla classe Developer, puoi mapparla esplicitamente a un'altra tabella aggiungendo l'annotazione @DynamoDBTable, come riportato nel seguente esempio di codice Java.

@DynamoDBTable(tableName="Managers")
public class Manager extends Developer { ...} 

DynamoDB TypeConverted

Annotazione per contrassegnare che una proprietà utilizza un convertitore di tipi personalizzato. Può essere annotata su un'annotazione definita dall'utente per passare proprietà aggiuntive a DynamoDBTypeConverter.

L'interfaccia DynamoDBTypeConverter consente di mappare i propri tipi di dati arbitrari a un tipo di dati supportato in nativo da DynamoDB. Per ulteriori informazioni, consulta Mappatura dei dati arbitrari.

DynamoDBTyped

Annotazione per sovrascrivere il vincolo del tipo di attributo standard. I tipi standard non richiedono l'annotazione se viene loro applicato il vincolo di attributo predefinito per quel tipo.

DynamoDB VersionAttribute

Identifica una proprietà di classe per archiviare un numero di versione di blocco ottimistico. DynamoDBMapper assegna un numero di versione a detta proprietà quando salva un nuovo item e lo incrementa ogni volta che lo aggiorni. Sono supportati soltanto i tipi scalari di numero. Per ulteriori informazioni sui tipi di dati, consulta Tipi di dati. Per ulteriori informazioni sulla funzione Controllo delle versioni, consulta Blocco ottimistico con il numero di versione.