Integra Spanner con Spring Data

Il modulo Spring Data Spanner ti aiuta a utilizzare Spanner in qualsiasi Java creata con Framework di primavera.

Come tutti i moduli Spring Data, Spring Data Spanner offre un modello di programmazione basato su Spring che conserva le garanzie di coerenza e scalabilità di Spanner. È sono simili a Spring Data JPA e ORM in modalità di sospensione, con annotazioni progettate per Spanner. Per ulteriori informazioni su come utilizzare JPA di Spring Data con Spanner, consulta Integra Spanner con Spring Data JPA (dialetto GoogleSQL).

Se hai già familiarità con Spring, Spring Data Spanner può semplifica l'utilizzo di Spanner nella tua applicazione e ridurre la quantità di codice che devi scrivere.

Questa pagina spiega come aggiungere Spring Data Spanner a un ambiente Java un'applicazione. Per informazioni dettagliate sul modulo, vedi Riferimento di Spring Data Spanner.

Installa il modulo

Se utilizzi Maven, aggiungi la Bill of Spring Cloud Materiali (BOM) e Spring Data Spanner al tuo file pom.xml. Queste dipendenze fornire i componenti Spring Data Spanner ai tuoi dati Spring ApplicationContext:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>spring-cloud-gcp-dependencies</artifactId>
      <version>3.7.7</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>${spring.boot.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-data-spanner</artifactId>
  </dependency>
</dependencies>

Devi anche creare un account di servizio e utilizzare la chiave dell'account di servizio per l'autenticazione con Google Cloud.

Per ulteriori informazioni, consulta le istruzioni per la configurazione di un ambiente di sviluppo Java. Non hai bisogno installare la libreria client di Google Cloud per Java; il comando iniziale Spring Boot installa automaticamente la libreria client.

Configura il modulo

Questa sezione descrive alcune delle impostazioni di configurazione più comunemente utilizzate Spanner dati Spring. Per un elenco completo delle impostazioni, vedi documentazione di riferimento.

Specifica un'istanza e un database

Per specificare l'istanza e il database predefiniti, imposta la configurazione seguente proprietà della tua applicazione:

Proprietà Descrizione
spring.cloud.gcp.spanner.project-id Facoltativo. L'ID del progetto Google Cloud. Sostituisce il valore spring.cloud.gcp.config.project-id.
spring.cloud.gcp.spanner.instance-id L'ID dell'istanza Spanner.
spring.cloud.gcp.spanner.database Il database a cui connettersi.

Dati Spanner del modello

Con Spring Data Spanner, puoi utilizzare oggetti Java (POJO) semplici e vecchi per modellare i dati archiviati nelle tabelle Spanner.

Per ogni tabella nel database, dichiara un'entità che rappresenta un record quella tabella. Utilizza le annotazioni per mappare l'entità e le sue proprietà a una tabella e tutte le sue colonne.

Puoi utilizzare le seguenti annotazioni per creare un modello di semplici relazioni tra entità e tabelle:

Annotazioni entità
@Column(name = "columnName")

Facoltativo. Mappa la proprietà a una colonna specifica nella Spanner, eseguendo l'override della strategia di denominazione automaticamente i nomi.

Se ometti questa proprietà, la strategia di denominazione predefinita per Spring Data Spanner mappa la proprietà Java camelCase ai nomi di colonna in PascalCase. Ad esempio, la proprietà singerId è mappata al nome della colonna SingerId.

@Embedded

Indica che la proprietà è un oggetto incorporato che può contenere i componenti di una chiave primaria. Se la proprietà viene effettivamente utilizzata chiave primaria, devi includere anche @PrimaryKey annotazione.

@Interleaved

@Interleaved(lazy = true)

Indica che una proprietà contiene un elenco di righe con con interleaving con la riga corrente.

Per impostazione predefinita, Spring Data Spanner recupera le righe con interleaving durante la creazione dell'istanza. Per recuperare le righe in modo lento, quando accedi alla utilizza @Interleaved(lazy = true).

Esempio: se un'entità Singer può avere interleaving Album voci come elementi secondari, aggiungi un proprietà List<Album> a Singer dell'oggetto. Inoltre, aggiungi un'annotazione @Interleaved alla proprietà.

@NotMapped

Indica che una proprietà non è archiviata nel database e deve essere ignorato.

@PrimaryKey

@PrimaryKey(keyOrder = N)

Indica che la proprietà è un componente della chiave primaria e identifica la posizione della proprietà all'interno della chiave primaria a partire da 1. Il valore predefinito di keyOrder è 1.

Esempio: @PrimaryKey(keyOrder = 3)

@Table(name = "TABLE_NAME")

La tabella modellata dall'entità. Ogni istanza dell'entità rappresenta un record nella tabella. Sostituisci TABLE_NAME con il nome della tabella.

Esempio: @Table(name = "Singers")

Se hai bisogno di modellare relazioni più complesse, consulta Riferimento di Spring Data Spanner per maggiori dettagli sulle altre annotazioni supportate dal modulo.

Gli esempi seguenti mostrano un modo per modellare le tabelle Singers e Albums per Spring Data Spanner:

  • Per le entità Singer, l'esempio include una proprietà albums, con un Annotazione @Interleaved. Questa proprietà contiene un elenco di album che sono con interleaving con l'entità Singer. Viene compilato automaticamente Spanner dei dati Spring automaticamente questa proprietà.
  • Per le entità Album, l'esempio include una proprietà relatedAlbums che è non sono archiviati in Spanner.
import com.google.cloud.spring.data.spanner.core.mapping.Interleaved;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;
import java.util.Date;
import java.util.List;


/**
 * An entity and table holding singers.
 */
@Table(name = "Singers")
public class Singer {
  @PrimaryKey
  long singerId;

  String firstName;

  String lastName;

  Date birthDate;

  @Interleaved
  List<Album> albums;
}
import com.google.cloud.spring.data.spanner.core.mapping.NotMapped;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;
import java.util.List;

/**
 * An entity class representing an Album.
 */
@Table(name = "Albums")
public class Album {

  @PrimaryKey
  long singerId;

  @PrimaryKey(keyOrder = 2)
  long albumId;

  String albumTitle;

  long marketingBudget;

  @NotMapped
  List<Album> relatedAlbums;

  public Album(long singerId, long albumId, String albumTitle, long marketingBudget) {
    this.singerId = singerId;
    this.albumId = albumId;
    this.albumTitle = albumTitle;
    this.marketingBudget = marketingBudget;
  }
}

Eseguire query e modificare i dati

Per eseguire query e modificare i dati con Spring Data Spanner, puoi acquisire un SpannerTemplate bean, che implementa SpannerOperations. SpannerTemplate fornisce metodi per eseguire query SQL e modificare i dati con istruzioni DML (Data Manipulation Language). Puoi anche utilizzare questo bean per accedere all'API Read e alla mutazione API per Spanner.

Inoltre, puoi estendere Interfaccia di SpannerRepository per incapsulare tutta la logica dell'applicazione che esegue query e modifica i dati in Spanner.

Le sezioni seguenti spiegano come lavorare con SpannerTemplate e SpannerRepository.

Acquisisci un bean di modello

Utilizza l'annotazione @Autowired per acquisire un bean SpannerTemplate automaticamente. Potrai quindi utilizzare SpannerTemplate in tutto il corso.

L'esempio seguente mostra una classe che acquisisce e utilizza il bean:

import com.google.cloud.spanner.KeySet;
import com.google.cloud.spanner.Statement;
import com.google.cloud.spring.data.spanner.core.SpannerQueryOptions;
import com.google.cloud.spring.data.spanner.core.SpannerTemplate;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * A quick start code for Spring Data Cloud Spanner. It demonstrates how to use SpannerTemplate to
 * execute DML and SQL queries, save POJOs, and read entities.
 */
@Component
public class SpannerTemplateSample {

  @Autowired
  SpannerTemplate spannerTemplate;

  public void runTemplateExample(Singer singer) {
    // Delete all of the rows in the Singer table.
    this.spannerTemplate.delete(Singer.class, KeySet.all());

    // Insert a singer into the Singers table.
    this.spannerTemplate.insert(singer);

    // Read all of the singers in the Singers table.
    List<Singer> allSingers = this.spannerTemplate
        .query(Singer.class, Statement.of("SELECT * FROM Singers"),
                new SpannerQueryOptions().setAllowPartialRead(true));
  }

}

Puoi utilizzare il bean SpannerTemplate per eseguire l'esecuzione in sola lettura transazioni e lettura/scrittura transazioni. Inoltre, puoi utilizzare @Transactional per creare informazioni transazioni.

Acquisisci un bean di repository

Se utilizzi un SpannerRepository, puoi utilizzare l'annotazione @Autowired per un bean che implementa l'interfaccia del repository. Un repository include metodi per eseguire funzioni Java come sola lettura transazioni e lettura/scrittura transazioni. Per operazioni di livello inferiore, puoi ottenere il bean di modelli utilizzato dal repository.

Gli esempi seguenti mostrano l'interfaccia di un repository e di una classe acquisisce e utilizza il bean:

import com.google.cloud.spanner.Key;
import com.google.cloud.spring.data.spanner.repository.SpannerRepository;
import com.google.cloud.spring.data.spanner.repository.query.Query;
import java.util.List;
import org.springframework.data.repository.query.Param;


/**
 * An interface of various Query Methods. The behavior of the queries is defined only by
 * their names, arguments, or annotated SQL strings. The implementation of these functions
 * is generated by Spring Data Cloud Spanner.
 */
public interface SingerRepository extends SpannerRepository<Singer, Key> {
  List<Singer> findByLastName(String lastName);

  int countByFirstName(String firstName);

  int deleteByLastName(String lastName);

  List<Singer> findTop3DistinctByFirstNameAndSingerIdIgnoreCaseOrLastNameOrderByLastNameDesc(
      String firstName, String lastName, long singerId);

  @Query("SELECT * FROM Singers WHERE firstName LIKE '%@fragment';")
  List<Singer> getByQuery(@Param("fragment") String firstNameFragment);
}
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * A quick start code for Spring Data Cloud Spanner.
 * It demonstrates how to use a SpannerRepository to execute read-write queries
 * generated from interface definitions.
 *
 */
@Component
public class SpannerRepositorySample {

  @Autowired
  SingerRepository singerRepository;

  public void runRepositoryExample() {
    List<Singer> lastNameSingers = this.singerRepository.findByLastName("a last name");

    int fistNameCount = this.singerRepository.countByFirstName("a first name");

    int deletedLastNameCount = this.singerRepository.deleteByLastName("a last name");
  }

}

Gestisci Spanner

Per ottenere informazioni sui tuoi database Spanner, aggiorna uno schema con un istruzione DDL (Data Definition Language) o completare altre attività amministrative puoi acquisire SpannerDatabaseAdminTemplate fagiolo.

Utilizza l'annotazione @Autowired per acquisire automaticamente il bean. Puoi quindi usa SpannerDatabaseAdminTemplate per tutto il corso.

L'esempio seguente mostra una classe che acquisisce e utilizza il bean:

import com.google.cloud.spring.data.spanner.core.admin.SpannerDatabaseAdminTemplate;
import com.google.cloud.spring.data.spanner.core.admin.SpannerSchemaUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * This sample demonstrates how to generate schemas for interleaved tables from POJOs and how to
 * execute DDL.
 */
@Component
public class SpannerSchemaToolsSample {

  @Autowired
  SpannerDatabaseAdminTemplate spannerDatabaseAdminTemplate;

  @Autowired
  SpannerSchemaUtils spannerSchemaUtils;

  /**
   * Creates the Singers table. Also creates the Albums table, because Albums is interleaved with
   * Singers.
   */
  public void createTableIfNotExists() {
    if (!this.spannerDatabaseAdminTemplate.tableExists("Singers")) {
      this.spannerDatabaseAdminTemplate.executeDdlStrings(
          this.spannerSchemaUtils
              .getCreateTableDdlStringsForInterleavedHierarchy(Singer.class),
          true);
    }
  }

  /**
   * Drops both the Singers and Albums tables using just a reference to the Singer entity type ,
   * because they are interleaved.
   */
  public void dropTables() {
    if (this.spannerDatabaseAdminTemplate.tableExists("Singers")) {
      this.spannerDatabaseAdminTemplate.executeDdlStrings(
          this.spannerSchemaUtils.getDropTableDdlStringsForInterleavedHierarchy(Singer.class),
          false);
    }
  }
}

Passaggi successivi