Verwenden Sie Erweiterungen

Die DynamoDB Enhanced Client API unterstützt Plugin-Erweiterungen, die Funktionen bieten, die über Mapping-Operationen hinausgehen. Erweiterungen haben zwei Hook-Methoden, undbeforeWrite(). afterRead() beforeWrite()ändert einen Schreibvorgang, bevor er stattfindet, und die afterRead() Methode ändert die Ergebnisse eines Lesevorgangs, nachdem er ausgeführt wurde. Da bei einigen Vorgängen (z. B. bei Elementaktualisierungen) sowohl ein Schreib- als auch ein Lesevorgang ausgeführt wird, werden beide Hook-Methoden aufgerufen.

Erweiterungen werden in der Reihenfolge geladen, in der sie im erweiterten Client Builder angegeben sind. Die Ladereihenfolge kann wichtig sein, da eine Erweiterung auf Werte reagieren kann, die durch eine vorherige Erweiterung transformiert wurden.

Die erweiterte Client-API enthält eine Reihe von Plugin-Erweiterungen, die sich im extensions Paket befinden. Standardmäßig lädt der erweiterte Client die VersionedRecordExtension und dieAtomicCounterExtension. Sie können das Standardverhalten mit dem Enhance Client Builder überschreiben und jede Erweiterung laden. Sie können auch keine angeben, wenn Sie die Standarderweiterungen nicht verwenden möchten.

Wenn Sie Ihre eigenen Erweiterungen laden, lädt der erweiterte Client keine Standarderweiterungen. Wenn Sie das Verhalten einer der Standarderweiterungen verwenden möchten, müssen Sie sie explizit zur Liste der Erweiterungen hinzufügen.

Im folgenden Beispiel verifyChecksumExtension wird eine benutzerdefinierte Erweiterung mit dem Namen geladenVersionedRecordExtension, die normalerweise standardmäßig von selbst geladen wird. Die AtomicCounterExtension ist in diesem Beispiel nicht geladen.

DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();

DynamoDbEnhancedClient enhancedClient = 
    DynamoDbEnhancedClient.builder()
                          .dynamoDbClient(dynamoDbClient)
                          .extensions(versionedRecordExtension, verifyChecksumExtension)
                          .build();

VersionedRecordExtension

Der VersionedRecordExtension wird standardmäßig geladen und erhöht die Versionsnummer eines Elements und verfolgt, wenn Elemente in die Datenbank geschrieben werden. Zu jedem Schreibvorgang wird eine Bedingung hinzugefügt, die dazu führt, dass der Schreibvorgang fehlschlägt, wenn die Versionsnummer des tatsächlich persistenten Elements nicht dem Wert entspricht, den die Anwendung zuletzt gelesen hat. Dieses Verhalten sorgt effektiv für optimistisches Sperren von Elementaktualisierungen. Wenn ein anderer Prozess ein Element zwischen dem Zeitpunkt aktualisiert, an dem der erste Prozess das Element gelesen hat und ein Update darauf geschrieben hat, schlägt der Schreibvorgang fehl.

Um anzugeben, welches Attribut verwendet werden soll, um die Versionsnummer des Elements nachzuverfolgen, kennzeichnen Sie ein numerisches Attribut im Tabellenschema.

Der folgende Ausschnitt gibt an, dass das version Attribut die Versionsnummer des Artikels enthalten soll.

    @DynamoDbVersionAttribute
    public Integer getVersion() {...};
    public void setVersion(Integer version) {...};

Der entsprechende Ansatz für ein statisches Tabellenschema wird im folgenden Codeausschnitt dargestellt.

    .addAttribute(Integer.class, a -> a.name("version")
                                       .getter(Customer::getVersion)
                                       .setter(Customer::setVersion)
                                        // Apply the 'version' tag to the attribute.
                                       .tags(VersionedRecordExtension.AttributeTags.versionAttribute())

AtomicCounterExtension

Das AtomicCounterExtension wird standardmäßig geladen und erhöht jedes Mal, wenn ein Datensatz in die Datenbank geschrieben wird, ein mit Tags versehenes numerisches Attribut. Start- und Inkrementwerte können angegeben werden. Wenn keine Werte angegeben sind, wird der Startwert auf 0 gesetzt und der Wert des Attributs wird um 1 erhöht.

Um anzugeben, welches Attribut ein Zähler ist, kennzeichnen Sie ein Attribut vom Typ Long im Tabellenschema.

Der folgende Ausschnitt zeigt die Verwendung der standardmäßigen Start- und Inkrementwerte für das Attribut. counter

    @DynamoDbAtomicCounter
    public Long getCounter() {...};
    public void setCounter(Long counter) {...};

Der Ansatz eines statischen Tabellenschemas wird im folgenden Codeausschnitt dargestellt. Die Atomic Counter Extension verwendet einen Startwert von 10 und erhöht den Wert jedes Mal, wenn der Datensatz geschrieben wird, um 5.

    .addAttribute(Integer.class, a -> a.name("counter")
                                       .getter(Customer::getCounter)
                                       .setter(Customer::setCounter)
                                        // Apply the 'atomicCounter' tag to the attribute with start and increment values.
                                       .tags(StaticAttributeTags.atomicCounter(10L, 5L))

AutoGeneratedTimestampRecordExtension

Jedes Mal, wenn das Element erfolgreich in die Datenbank geschrieben wurde, werden die markierten Attribute des Typs AutoGeneratedTimestampRecordExtension automatisch Instant mit einem aktuellen Zeitstempel aktualisiert.

Diese Erweiterung ist standardmäßig nicht geladen. Daher müssen Sie sie als benutzerdefinierte Erweiterung angeben, wenn Sie den erweiterten Client erstellen, wie im ersten Beispiel in diesem Thema gezeigt.

Um anzugeben, welches Attribut mit dem aktuellen Zeitstempel aktualisiert werden soll, kennzeichnen Sie das Instant Attribut im Tabellenschema.

Das lastUpdate Attribut ist das Ziel des Erweiterungsverhaltens im folgenden Codeausschnitt. Beachten Sie die Anforderung, dass das Attribut ein Instant Typ sein muss.

    @DynamoDbAutoGeneratedTimestampAttribute
    public Instant getLastUpdate() {...}
    public void setLastUpdate(Instant lastUpdate) {...}

Der entsprechende Ansatz für ein statisches Tabellenschema wird im folgenden Codeausschnitt dargestellt.

     .addAttribute(Instant.class, a -> a.name("lastUpdate")
                                        .getter(Customer::getLastUpdate)
                                        .setter(Customer::setLastUpdate)
                                        // Applying the 'autoGeneratedTimestamp' tag to the attribute.
                                        .tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())

Benutzerdefinierte Erweiterungen

Die folgende benutzerdefinierte Erweiterungsklasse zeigt eine beforeWrite() Methode, die einen Aktualisierungsausdruck verwendet. Nach Kommentarzeile 2 erstellen wir ein, SetAction um das registrationDate Attribut festzulegen, falls das Element in der Datenbank noch kein registrationDate Attribut hat. Immer wenn ein Customer Objekt aktualisiert wird, stellt die Erweiterung sicher, dass a gesetzt registrationDate ist.

public final class CustomExtension implements DynamoDbEnhancedClientExtension {

    // 1. In a custom extension, use an UpdateExpression to define what action to take before
    //    an item is updated.
    @Override
    public WriteModification beforeWrite(DynamoDbExtensionContext.BeforeWrite context) {
        if ( context.operationContext().tableName().equals("Customer")
                && context.operationName().equals(OperationName.UPDATE_ITEM)) {
            return WriteModification.builder()
                    .updateExpression(createUpdateExpression())
                    .build();
        }
        return WriteModification.builder().build();  // Return an "empty" WriteModification instance if the extension should not be applied.
                                                     // In this case, if the code is not updating an item on the Customer table.
    }

    private static UpdateExpression createUpdateExpression() {

        // 2. Use a SetAction, a subclass of UpdateAction, to provide the values in the update.
        SetAction setAction =
                SetAction.builder()
                        .path("registrationDate")
                        .value("if_not_exists(registrationDate, :regValue)")
                        .putExpressionValue(":regValue", AttributeValue.fromS(Instant.now().toString()))
                        .build();
        // 3. Build the UpdateExpression with one or more UpdateAction.
        return UpdateExpression.builder()
                .addAction(setAction)
                .build();
    }
}