Creare la prima applicazione Java Reliable Actors di Service Fabric in LinuxCreate your first Java Service Fabric Reliable Actors application on Linux

Questa guida introduttiva consente di creare in pochi minuti la prima applicazione Java di Azure Service Fabric in un ambiente di sviluppo Linux.This quick-start helps you create your first Azure Service Fabric Java application in a Linux development environment in just a few minutes. Al termine, si avrà una semplice applicazione Java con un singolo servizio in esecuzione nel cluster di sviluppo locale.When you are finished, you'll have a simple Java single-service application running on the local development cluster.

PrerequisitiPrerequisites

Prima di iniziare, installare Service Fabric SDK e l'interfaccia della riga di comando di Service Fabric e configurare un cluster di sviluppo nell'ambiente di sviluppo Linux.Before you get started, install the Service Fabric SDK, the Service Fabric CLI, and setup a development cluster in your Linux development environment. Se si usa Mac OS X, è possibile configurare un ambiente di sviluppo Linux in una macchina virtuale usando Vagrant.If you are using Mac OS X, you can set up a Linux development environment in a virtual machine using Vagrant.

Installare anche l'interfaccia della riga di comando di Service Fabric.Also install the Service Fabric CLI.

Installare e configurare i generatori per JavaInstall and set up the generators for Java

Service Fabric offre gli strumenti di scaffolding che consentono di creare un'applicazione Java di Service Fabric dal terminale tramite il generatore di modelli Yeoman.Service Fabric provides scaffolding tools which will help you create a Service Fabric Java application from terminal using Yeoman template generator. Seguire questa procedura per assicurarsi che nella macchina virtuale sia disponibile il generatore di modelli Yeoman di Service Fabric per Java.Please follow the steps below to ensure you have the Service Fabric yeoman template generator for Java working on your machine.

  1. Installare nodejs e NPM nella macchina virtualeInstall nodejs and NPM on your machine

    sudo apt-get install npm
    sudo apt install nodejs-legacy
    
  2. Installare il generatore di modelli Yeoman nella macchina virtuale da NPMInstall Yeoman template generator on your machine from NPM

    sudo npm install -g yo
    
  3. Installare il generatore di applicazioni Java Yeoman di Service Fabric da NPMInstall the Service Fabric Yeoman Java application generator from NPM

    sudo npm install -g generator-azuresfjava
    

Concetti di baseBasic concepts

Per iniziare a usare Reliable Actors, è sufficiente comprendere solo alcuni concetti di base:To get started with Reliable Actors, you only need to understand a few basic concepts:

  • Servizio attore.Actor service. Reliable Actors viene fornito in pacchetti di servizi Reliable Services che possono essere distribuiti nell'infrastruttura Service Fabric.Reliable Actors are packaged in Reliable Services that can be deployed in the Service Fabric infrastructure. Le istanze di Actors vengono attivate in un'istanza del servizio denominata.Actor instances are activated in a named service instance.
  • Registrazione attore.Actor registration. Come con Reliable Services, un servizio Reliable Actor deve essere registrato con il runtime di Service Fabric.As with Reliable Services, a Reliable Actor service needs to be registered with the Service Fabric runtime. In più, il tipo di attore deve essere registrato con il runtime di Actor.In addition, the actor type needs to be registered with the Actor runtime.
  • Interfaccia attore.Actor interface. Questa interfaccia viene usata per definire l'interfaccia pubblica fortemente tipizzata di un attore.The actor interface is used to define a strongly typed public interface of an actor. In base alla terminologia modello di Reliable Actors, questa interfaccia definisce i tipi di messaggi che l'attore può comprendere ed eseguire.In the Reliable Actor model terminology, the actor interface defines the types of messages that the actor can understand and process. L'interfaccia attore viene usata da altri attori o applicazioni client per "inviare" messaggi all'attore (in modo asincrono).The actor interface is used by other actors and client applications to "send" (asynchronously) messages to the actor. Reliable Actors può implementare più interfacce.Reliable Actors can implement multiple interfaces.
  • Classe ActorProxy.ActorProxy class. La classe ActorProxy viene usata dalle applicazioni client per richiamare i metodi esposti tramite l'interfaccia attore.The ActorProxy class is used by client applications to invoke the methods exposed through the actor interface. La classe ActorProxy fornisce due funzionalità importanti:The ActorProxy class provides two important functionalities:

    • Risoluzione dei nomi: la classe è in grado di individuare l'attore nel cluster, ossia trovare il nodo del cluster in cui è ospitato.Name resolution: It is able to locate the actor in the cluster (find the node of the cluster where it is hosted).
    • Gestione degli errori: la classe può ripetere le chiamate al metodo e risolvere nuovamente la posizione dell'attore, ad esempio dopo un errore che richiede lo spostamento dell'attore in un altro nodo del cluster.Failure handling: It can retry method invocations and re-resolve the actor location after, for example, a failure that requires the actor to be relocated to another node in the cluster.

È opportuno citare le regole seguenti relative alle interfacce dell'attore:The following rules that pertain to actor interfaces are worth mentioning:

  • I metodi di interfaccia dell'attore non possono essere sottoposti a overload.Actor interface methods cannot be overloaded.
  • I metodi di interfaccia dell'attore non accettano parametri facoltativi, out o ref.Actor interface methods must not have out, ref, or optional parameters.
  • Non sono supportate interfacce generiche.Generic interfaces are not supported.

Creazione dell'applicazioneCreate the application

Un'applicazione di Service Fabric contiene uno o più servizi, ognuno dei quali contribuisce alle funzionalità dell'applicazione con un ruolo specifico.A Service Fabric application contains one or more services, each with a specific role in delivering the application's functionality. Il generatore installato nell'ultima sezione semplifica la creazione del primo servizio e l'aggiunta di altri servizi in un secondo momento.The generator you installed in the last section, makes it easy to create your first service and to add more later. È anche possibile creare, compilare e distribuire applicazioni Java di Service Fabric usando un plug-in per Eclipse.You can also create, build, and deploy Service Fabric Java applications using a plugin for Eclipse. Vedere Creare e distribuire la prima applicazione Java usando Eclipse.See Create and deploy your first Java application using Eclipse. Per questa guida introduttiva, usare Yeoman per creare un'applicazione con un unico servizio per archiviare e ottenere un valore del contatore.For this quick start, use Yeoman to create an application with a single service that stores and gets a counter value.

  1. In un terminale digitare yo azuresfjava.In a terminal, type yo azuresfjava.
  2. Assegnare un nome all'applicazione.Name your application.
  3. Scegliere il tipo del primo servizio e assegnargli un nome.Choose the type of your first service and name it. Per questa esercitazione, scegliere un servizio Reliable Actor.For this tutorial, choose a Reliable Actor Service. Per altre informazioni sugli altri tipi di servizi, vedere Panoramica dei modelli di programmazione di Service Fabric.For more information about the other types of services, see Service Fabric programming model overview. Generatore Yeoman di Service Fabric per JavaService Fabric Yeoman generator for Java

Se si assegna il nome "HelloWorldActorApplication" all'applicazione e "HelloWorldActor" all'attore, viene creato lo scaffolding seguente:If you name the application "HelloWorldActorApplication" and the actor "HelloWorldActor", the following scaffolding is created:

HelloWorldActorApplication/
├── build.gradle
├── HelloWorldActor
│   ├── build.gradle
│   ├── settings.gradle
│   └── src
│       └── reliableactor
│           ├── HelloWorldActorHost.java
│           └── HelloWorldActorImpl.java
├── HelloWorldActorApplication
│   ├── ApplicationManifest.xml
│   └── HelloWorldActorPkg
│       ├── Code
│       │   ├── entryPoint.sh
│       │   └── _readme.txt
│       ├── Config
│       │   ├── _readme.txt
│       │   └── Settings.xml
│       ├── Data
│       │   └── _readme.txt
│       └── ServiceManifest.xml
├── HelloWorldActorInterface
│   ├── build.gradle
│   └── src
│       └── reliableactor
│           └── HelloWorldActor.java
├── HelloWorldActorTestClient
│   ├── build.gradle
│   ├── settings.gradle
│   ├── src
│   │   └── reliableactor
│   │       └── test
│   │           └── HelloWorldActorTestClient.java
│   └── testclient.sh
├── install.sh
├── settings.gradle
└── uninstall.sh

Blocchi predefiniti di base di Reliable ActorsReliable Actors basic building blocks

I concetti fondamentali descritti in precedenza si traducono nei blocchi predefiniti di base di un servizio Reliable Actor.The basic concepts described earlier translate into the basic building blocks of a Reliable Actor service.

Interfaccia dell'attoreActor interface

Questo blocco include la definizione dell'interfaccia per l'attore.This contains the interface definition for the actor. Questa interfaccia definisce il contratto dell'attore che è condiviso dall'implementazione dell'attore e i client che chiamano l'attore, quindi è in genere opportuno definirlo in una posizione separata rispetto all'implementazione dell'attore e può essere condiviso da molti altri servizi o applicazioni client.This interface defines the actor contract that is shared by the actor implementation and the clients calling the actor, so it typically makes sense to define it in a place that is separate from the actor implementation and can be shared by multiple other services or client applications.

HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java:HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java:

public interface HelloWorldActor extends Actor {
    @Readonly   
    CompletableFuture<Integer> getCountAsync();

    CompletableFuture<?> setCountAsync(int count);
}

Servizio ActorActor service

Questo blocco contiene l'implementazione dell'attore e il codice di registrazione dell'attore.This contains your actor implementation and actor registration code. La classe dell'attore implementa l'interfaccia dell'attore.The actor class implements the actor interface. Questa è la posizione in cui l'attore svolge il suo lavoro.This is where your actor does its work.

HelloWorldActor/src/reliableactor/HelloWorldActorImpl:HelloWorldActor/src/reliableactor/HelloWorldActorImpl:

@ActorServiceAttribute(name = "HelloWorldActor.HelloWorldActorService")
@StatePersistenceAttribute(statePersistence = StatePersistence.Persisted)
public class HelloWorldActorImpl extends ReliableActor implements HelloWorldActor {
    Logger logger = Logger.getLogger(this.getClass().getName());

    protected CompletableFuture<?> onActivateAsync() {
        logger.log(Level.INFO, "onActivateAsync");

        return this.stateManager().tryAddStateAsync("count", 0);
    }

    @Override
    public CompletableFuture<Integer> getCountAsync() {
        logger.log(Level.INFO, "Getting current count value");
        return this.stateManager().getStateAsync("count");
    }

    @Override
    public CompletableFuture<?> setCountAsync(int count) {
        logger.log(Level.INFO, "Setting current count value {0}", count);
        return this.stateManager().addOrUpdateStateAsync("count", count, (key, value) -> count > value ? count : value);
    }
}

Registrazione dell'attoreActor registration

Il servizio Actor deve essere registrato con un tipo di servizio nel runtime di Service Fabric.The actor service must be registered with a service type in the Service Fabric runtime. Perché il servizio Actor possa eseguire le istanze degli attori, è necessario che anche il proprio tipo di attore sia registrato con il servizio Actor.In order for the Actor Service to run your actor instances, your actor type must also be registered with the Actor Service. Il metodo di registrazione ActorRuntime esegue questa attività per gli attori.The ActorRuntime registration method performs this work for actors.

HelloWorldActor/src/reliableactor/HelloWorldActorHost:HelloWorldActor/src/reliableactor/HelloWorldActorHost:

public class HelloWorldActorHost {

    public static void main(String[] args) throws Exception {

        try {
            ActorRuntime.registerActorAsync(HelloWorldActorImpl.class, (context, actorType) -> new ActorServiceImpl(context, actorType, ()-> new HelloWorldActorImpl()), Duration.ofSeconds(10));

            Thread.sleep(Long.MAX_VALUE);

        } catch (Exception e) {
            e.printStackTrace();
            throw e;
        }
    }
}

Compilare l'applicazione.Build the application

I modelli Yeoman di Service Fabric includono uno script di compilazione per Gradle, che può essere usato per compilare l'applicazione dal terminale.The Service Fabric Yeoman templates include a build script for Gradle, which you can use to build the application from the terminal. Le dipendenze Java di Service Fabric vengono recuperate da Maven.Service Fabric Java dependencies get fetched from Maven. Per compilare e usare le applicazioni Java di Service Fabric, è necessario verificare che siano installati JDK e Gradle.To build and work on the Service Fabric Java applications, you need to ensure that you have JDK and Gradle installed. Se non sono ancora installati, è possibile eseguire questi comandi per installare JDK (openjdk-8-jdk) e Gradle:If not yet installed, you can run the following to install JDK(openjdk-8-jdk) and Gradle -

sudo apt-get install openjdk-8-jdk-headless
sudo apt-get install gradle

Per compilare l'applicazione e creare il pacchetto, eseguire questo comando:To build and package the application, run the following:

cd myapp
gradle

Distribuire l'applicazioneDeploy the application

Dopo aver compilato l'applicazione, è possibile distribuirla nel cluster locale.Once the application is built, you can deploy it to the local cluster.

  1. Connettersi al cluster locale di Service Fabric.Connect to the local Service Fabric cluster.

    sfctl cluster select --endpoint http://localhost:19080
    
  2. Eseguire lo script di installazione messo a disposizione nel modello per copiare il pacchetto dell'applicazione nell'archivio immagini del cluster, registrare il tipo di applicazione e creare un'istanza dell'applicazione.Run the install script provided in the template to copy the application package to the cluster's image store, register the application type, and create an instance of the application.

    ./install.sh
    

La distribuzione dell'applicazione compilata è uguale a quella di qualsiasi altra applicazione di Service Fabric.Deploying the built application is the same as any other Service Fabric application. Per istruzioni dettagliate, vedere la documentazione sulla gestione di un'applicazione di Service Fabric con l'interfaccia della riga di comando di Service Fabric.See the documentation on managing a Service Fabric application with the Service Fabric CLI for detailed instructions.

I parametri per questi comandi si trovano nei manifesti generati nel pacchetto dell'applicazione.Parameters to these commands can be found in the generated manifests inside the application package.

Dopo la distribuzione dell'applicazione, aprire un browser e passare a Service Fabric Explorer all'indirizzo http://localhost:19080/Explorer.Once the application has been deployed, open a browser and navigate to Service Fabric Explorer at http://localhost:19080/Explorer. Espandere quindi il nodo Applicazioni, nel quale sarà ora presente una voce per il tipo di applicazione e un'altra per la prima istanza del tipo.Then, expand the Applications node and note that there is now an entry for your application type and another for the first instance of that type.

Avviare il client di test ed eseguire un failoverStart the test client and perform a failover

Gli attori non eseguono alcuna operazione in modo indipendente, ma richiedono un altro servizio o client per l'invio dei messaggi.Actors do not do anything on their own, they require another service or client to send them messages. Il modello Actor include un semplice script di test che è possibile usare per interagire con il servizio Actor.The actor template includes a simple test script that you can use to interact with the actor service.

  1. Eseguire lo script tramite l'utilità delle espressioni di controllo per visualizzare l'output del servizio Actor.Run the script using the watch utility to see the output of the actor service. Lo script di test chiama il metodo setCountAsync() nell'attore per incrementare un contatore, chiama il metodo getCountAsync() nell'attore per ottenere il nuovo valore del contatore e visualizza tale valore nella console.The test script calls the setCountAsync() method on the actor to increment a counter, calls the getCountAsync() method on the actor to get the new counter value, and displays that value to the console.

    cd myactorsvcTestClient
    watch -n 1 ./testclient.sh
    
  2. In Service Fabric Explorer individuare il nodo che ospita la replica primaria del servizio Actor.In Service Fabric Explorer, locate the node hosting the primary replica for the actor service. Nello screenshot seguente si tratta del nodo 3.In the screenshot below, it is node 3. La replica di servizi primaria gestisce le operazioni di lettura e scrittura.The primary service replica handles read and write operations. Le modifiche allo stato del servizio vengono quindi replicate nelle repliche secondarie, in esecuzione nei nodi 0 e 1 nello screenshot seguente.Changes in service state are then replicated out to the secondary replicas, running on nodes 0 and 1 in the screen shot below.

    Ricerca della replica primaria in Service Fabric Explorer

  3. In Nodi fare clic sul nodo trovato nel passaggio precedente e quindi scegliere Disattiva (riavvio) dal menu Azioni.In Nodes, click the node you found in the previous step, then select Deactivate (restart) from the Actions menu. Questa azione consente di riavviare il nodo che esegue la replica di servizi primaria e di forzare il failover in una delle repliche secondarie in esecuzione in un altro nodo.This action restarts the node running the primary service replica and forces a failover to one of the secondary replicas running on another node. Questa replica secondaria viene alzata di livello a primaria, un'altra replica secondaria viene creata in un nodo diverso e la replica primaria inizia a eseguire operazioni di lettura/scrittura.That secondary replica is promoted to primary, another secondary replica is created on a different node, and the primary replica begins to take read/write operations. Durante il riavvio del nodo, osservare l'output dal client di test e notare che l'incremento del contatore prosegue nonostante il failover.As the node restarts, watch the output from the test client and note that the counter continues to increment despite the failover.

Rimuovere l'applicazioneRemove the application

Usare lo script di disinstallazione incluso nel modello per eliminare l'istanza dell'applicazione, annullare la registrazione del pacchetto dell'applicazione e rimuovere tale pacchetto dall'archivio immagini del cluster.Use the uninstall script provided in the template to delete the application instance, unregister the application package, and remove the application package from the cluster's image store.

./uninstall.sh

In Service Fabric Explorer si noterà che l'applicazione e il tipo di applicazione non sono più visualizzati nel nodo Applicazioni.In Service Fabric explorer you see that the application and application type no longer appear in the Applications node.

Librerie Java di Service Fabric in MavenService Fabric Java libraries on Maven

Le librerie Java di Service Fabric sono ospitate in Maven.Service Fabric Java libraries have been hosted in Maven. È possibile aggiungere le dipendenze nel file pom.xml o build.gradle dei progetti per usare le librerie Java di Service Fabric da mavenCentral.You can add the dependencies in the pom.xml or build.gradle of your projects to use Service Fabric Java libraries from mavenCentral.

ActorActors

Supporto di Service Fabric Reliable Actors per l'applicazione.Service Fabric Reliable Actor support for your application.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-actors-preview</artifactId>
    <version>0.12.0</version>
</dependency>
repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-actors-preview:0.12.0'
}

ServicesServices

Supporto delle applicazioni Reliable Services di Service Fabric per l'applicazione in uso.Service Fabric Reliable Services support for your application.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-services-preview</artifactId>
    <version>0.12.0</version>
</dependency>
repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-services-preview:0.12.0'
}

AltroOthers

TrasportoTransport

Supporto del livello trasporto per l'applicazione Java di Service Fabric.Transport layer support for Service Fabric Java application. Non è necessario aggiungere esplicitamente questa dipendenza alle applicazioni Reliable Actors o Services, a meno che non si esegua la programmazione al livello trasporto.You do not need to explicitly add this dependency to your Reliable Actor or Service applications, unless you program at the transport layer.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-transport-preview</artifactId>
    <version>0.12.0</version>
</dependency>
repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-transport-preview:0.12.0'
}

Supporto di FabricFabric support

Supporto a livello di sistema per Service Fabric, che comunica con il runtime nativo di Service Fabric.System level support for Service Fabric, which talks to native Service Fabric runtime. Non è necessario aggiungere esplicitamente questa dipendenza alle applicazioni Reliable Actors o Services.You do not need to explicitly add this dependency to your Reliable Actor or Service applications. Viene recuperata automaticamente da Maven quando si includono le altre dipendenze riportate sopra.This gets fetched automatically from Maven, when you include the other dependencies above.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-preview</artifactId>
    <version>0.12.0</version>
</dependency>
repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-preview:0.12.0'
}

Migrazione di applicazioni Java di Service Fabric precedenti da usare con MavenMigrating old Service Fabric Java applications to be used with Maven

Le librerie Java di Service Fabric sono state recentemente spostate da Service Fabric Java SDK al repository di Maven.We have recently moved Service Fabric Java libraries from Service Fabric Java SDK to Maven repository. Benché le nuove applicazioni generate con Yeoman o Eclipse genereranno i progetti aggiornati più recenti (in grado di interagire con Maven), è possibile aggiornare le applicazioni Java esistenti di Service Fabric senza stato o actor, che in precedenza usavano Service Fabric Java SDK, in modo che usino le dipendenze Java di Service Fabric da Maven.While the new applications you generate using Yeoman or Eclipse, will generate latest updated projects (which will be able to work with Maven), you can update your existing Service Fabric stateless or actor Java applications, which were using the Service Fabric Java SDK earlier, to use the Service Fabric Java dependencies from Maven. Seguire la procedura riportata qui per assicurare che l'applicazione precedente funzioni con Maven.Please follow the steps mentioned here to ensure your older application works with Maven.

Passaggi successiviNext steps