Tworzenie pierwszej aplikacji Java z interfejsem Reliable Actors usługi Service Fabric w systemie Linux

Artykuł
06/01/2023

Ten przewodnik Szybki start pomaga w ciągu kilku minut utworzyć pierwszą aplikację Java usługi Azure Service Fabric w środowisku projektowym w systemie Linux. W wyniku pracy z przewodnikiem zostanie utworzona prosta jednousługowa aplikacja Java uruchamiana w lokalnym klastrze projektowym.

Wymagania wstępne

Przed rozpoczęciem zainstaluj zestaw SDK usługi Service Fabric, interfejs wiersza polecenia usługi Service Fabric i narzędzie Yeoman, a także skonfiguruj środowisko projektowe języka Java i klaster projektowy w środowisku projektowym w systemie Linux. Jeśli używasz systemu Mac OS X, możesz skonfigurować środowisko projektowe na komputerze Mac za pomocą platformy Docker.

Zainstaluj także interfejs wiersza polecenia usługi Service Fabric.

Instalowanie i konfigurowanie generatorów dla języka Java

Usługa Service Fabric udostępnia narzędzia do tworzenia szkieletu, które ułatwiają tworzenie aplikacji Java usługi Service Fabric z poziomu terminalu przy użyciu generatora szablonów Yeoman. Jeśli narzędzie Yeoman nie jest jeszcze zainstalowane, zobacz Service Fabric getting started with Linux (Pierwsze kroki z usługą Service Fabric w systemie Linux), aby uzyskać instrukcje konfigurowania narzędzia Yeoman. Uruchom następujące polecenie, aby zainstalować generator szablonów narzędzia Yeoman usługi Service Fabric dla języka Java.

npm install -g generator-azuresfjava

Podstawowe pojęcia

Aby rozpocząć pracę z elementami Reliable Actors, musisz tylko poznać kilka podstawowych pojęć:

Usługa aktora. Elementy Reliable Actors są spakowane w usługach Reliable Services, które można wdrożyć w infrastrukturze usługi Service Fabric. Wystąpienia aktora są aktywowane w nazwanym wystąpieniu usługi.
Rejestracja aktora. Podobnie jak w przypadku usług Reliable Services, usługę Reliable Actor należy zarejestrować w środowisku uruchomieniowym usługi Service Fabric. Ponadto typ aktora należy zarejestrować w środowisku uruchomieniowym aktora.
Interfejs aktora. Interfejs aktora służy do definiowania jednoznacznie określonego interfejsu publicznego aktora. W terminologii modelu usługi Reliable Actor interfejs aktora definiuje typy komunikatów, które może zrozumieć i przetworzyć aktor. Interfejs aktora jest używany przez innych aktorów i aplikacje klienckie do „wysyłania” (asynchronicznie) komunikatów do aktora. W usługi Reliable Actors można zaimplementować wiele interfejsów.
Klasa ActorProxy. Klasa ActorProxy jest używana przez aplikacje klienckie do wywołania metod ujawnianych za pośrednictwem interfejsu aktora. Klasa ActorProxy udostępnia dwie ważne funkcje:
- Rozpoznawanie nazw: jest w stanie zlokalizować aktora w klastrze (znaleźć węzeł klastra, w którym jest on hostowany).
- Obsługa błędów: może ponawiać próby wywołania metody i ponownie rozpoznawać lokalizację aktora, na przykład po wystąpieniu błędu, który wymaga przeniesienia aktora do innego węzła w klastrze.

Warto wspomnieć o następujących regułach odnoszących się do interfejsów aktora:

Metod interfejsu aktora nie można przeciążyć.
Metody interfejsu aktora nie mogą zawierać parametrów out, ref ani parametrów opcjonalnych.
Interfejsy ogólne nie są obsługiwane.

Tworzenie aplikacji

Aplikacja usługi Service Fabric zawiera jedną lub więcej usług, a każda z nich pełni określoną rolę w dostarczaniu funkcjonalności aplikacji. Generator, który został zainstalowany w ostatniej sekcji, ułatwia utworzenie pierwszej usługi i dodawanie kolejnych w przyszłości. Możesz też tworzyć, kompilować i wdrażać aplikacje Java usługi Service Fabric przy użyciu wtyczki dla środowiska Eclipse. Zobacz Create and deploy your first Java application using Eclipse (Tworzenie i wdrażanie pierwszej aplikacji Java za pomocą środowiska Eclipse). Na potrzeby tego przewodnika Szybki start użyj narzędzia Yeoman, aby utworzyć aplikację z jedną usługą, w której jest przechowywana i pobierana wartość licznika.

Na terminalu wpisz yo azuresfjava.
Nadaj nazwę aplikacji.
Wybierz typ pierwszej usługi i nadaj jej nazwę. Na potrzeby tego samouczka wybierz usługę Reliable Actor Service. Aby uzyskać więcej informacji o pozostałych typach usług, zobacz Service Fabric programming model overview (Omówienie modelu programowania usługi Service Fabric).

Jeśli aplikacja otrzyma nazwę „HelloWorldActorApplication”, a aktor — „HelloWorldActor”, zostanie utworzony następujący szkielet:

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

Podstawowe bloki konstrukcyjne usługi Reliable Actors

Podstawowe pojęcia opisane powyżej można przełożyć na podstawowe bloki konstrukcyjne usługi Reliable Actor.

Interfejs aktora

Zawiera definicję interfejsu aktora. Ten interfejs definiuje kontrakt aktora udostępniany implementacji aktora i klientom wywołującym aktora, dlatego zazwyczaj warto zdefiniować go w miejscu, które jest oddzielone od implementacji aktora i może zostać udostępnione wielu innym usługom lub aplikacjom klienckim.

HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java:

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

    CompletableFuture<?> setCountAsync(int count);
}

Usługa aktora

Zawiera implementację aktora i kod rejestracji aktora. Klasa aktora implementuje interfejs aktora. Jest to miejsce, gdzie aktor wykonuje swoją pracę.

HelloWorldActor/src/reliableactor/HelloWorldActorImpl:

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

    public HelloWorldActorImpl(FabricActorService actorService, ActorId actorId){
        super(actorService, actorId);
    }

    @Override
    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);
    }
}

Rejestracja aktora

Usługę aktora należy zarejestrować za pomocą typu usługi w środowisku uruchomieniowym usługi Service Fabric. Aby usługa aktora uruchamiała wystąpienia aktora, w usłudze aktora należy również zarejestrować typ aktora. Metoda rejestracji ActorRuntime wykonuje tę pracę dla aktorów.

HelloWorldActor/src/reliableactor/HelloWorldActorHost:

public class HelloWorldActorHost {

private static final Logger logger = Logger.getLogger(HelloWorldActorHost.class.getName());

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

        try {

            ActorRuntime.registerActorAsync(HelloWorldActorImpl.class, (context, actorType) -> new FabricActorService(context, actorType, (a,b)-> new HelloWorldActorImpl(a,b)), Duration.ofSeconds(10));
            Thread.sleep(Long.MAX_VALUE);
        } catch (Exception e) {
            logger.log(Level.SEVERE, "Exception occurred", e);
            throw e;
        }
    }
}

Kompilowanie aplikacji

Szablony generatora Yeoman usługi Service Fabric obejmują skrypt kompilacji dla narzędzia Gradle, którego można użyć do skompilowania aplikacji z poziomu terminalu. Zależności aplikacji Java usługi Service Fabric są pobierane z narzędzia Maven. Aby kompilować aplikacje Java usługi Service Fabric i pracować nad nimi, upewnij się, że zainstalowano zestaw JDK i narzędzie Gradle. Jeśli nie są jeszcze zainstalowane, zobacz Service Fabric getting started with Linux (Pierwsze kroki z usługą Service Fabric w systemie Linux), aby uzyskać instrukcje instalacji zestawu JDK i narzędzia Gradle.

Aby skompilować aplikację i utworzyć jej pakiet, uruchom następujące polecenie:

cd HelloWorldActorApplication
gradle

Wdrażanie aplikacji

Skompilowaną aplikację można wdrożyć w klastrze lokalnym.

Nawiąż połączenie z lokalnym klastrem usługi Service Fabric (klaster musi być skonfigurowany i uruchomiony).
```
sfctl cluster select --endpoint http://localhost:19080
```
Uruchom skrypt instalacji udostępniony w szablonie, aby skopiować pakiet aplikacji do magazynu obrazów klastra, zarejestrować typ aplikacji i utworzyć wystąpienie aplikacji.
```
./install.sh
```

Wdrażanie skompilowanej aplikacji przebiega tak samo jak w przypadku innych aplikacji usługi Service Fabric. Szczegółowe instrukcje są dostępne w dokumentacji dotyczącej zarządzania aplikacją usługi Service Fabric za pomocą interfejsu wiersza polecenia usługi Service Fabric.

Parametry tych poleceń można znaleźć w manifestach wygenerowanych w pakiecie aplikacji.

Po wdrożeniu aplikacji otwórz przeglądarkę i przejdź do narzędzia Service Fabric Explorer pod adresem http://localhost:19080/Explorer. Następnie rozwiń węzeł Aplikacje i zwróć uwagę, że istnieje teraz wpis dla danego typu aplikacji i inny wpis dla pierwszego wystąpienia tego typu.

Ważne

Aby wdrożyć aplikację w bezpiecznym klastrze systemu Linux na platformie Azure, należy skonfigurować certyfikat w celu zweryfikowania aplikacji przy użyciu środowiska uruchomieniowego usługi Service Fabric. Dzięki temu usługi Reliable Actors mogą komunikować się z podstawowymi interfejsami API środowiska uruchomieniowego usługi Service Fabric. Aby dowiedzieć się więcej, zobacz Konfigurowanie aplikacji Reliable Services do uruchamiania w klastrach systemu Linux.

Uruchamianie klienta testowego i przechodzenie w tryb failover

Aktorzy nie pełnią samodzielnie żadnej funkcji. Wymagają wysyłania do nich komunikatów przez inną usługę lub innego klienta. Szablon aktora zawiera prosty skrypt testowy, którego można użyć do interakcji z usługą aktora.

Uwaga

Klient testowy używa klasy ActorProxy do komunikowania się z aktorami, które muszą działać w tym samym klastrze co usługa aktora lub współużytkować tę samą przestrzeń adresową IP. Możesz uruchomić klienta testowego na tym samym komputerze co lokalny klaster deweloperów. Aby komunikować się z aktorami w klastrze zdalnym, należy jednak wdrożyć bramę w klastrze obsługującym komunikację zewnętrzną z aktorami.

Uruchom skrypt za pomocą narzędzia kontrolnego, aby wyświetlić dane wyjściowe usługi aktora. Skrypt testowy wywołuje metodę setCountAsync() dla aktora w celu zwiększenia wartości licznika, wywołuje metodę getCountAsync() dla aktora w celu pobrania nowej wartości licznika i wyświetla tę wartość w konsoli.

W przypadku systemu MAC OS X należy skopiować folder HelloWorldTestClient do lokalizacji wewnątrz kontenera, uruchamiając następujące dodatkowe polecenia.
```
 docker cp HelloWorldTestClient [first-four-digits-of-container-ID]:/home
 docker exec -it [first-four-digits-of-container-ID] /bin/bash
 cd /home
```
```
cd HelloWorldActorTestClient
watch -n 1 ./testclient.sh
```
W narzędziu Service Fabric Explorer zlokalizuj węzeł, w którym znajduje się replika podstawowa usługi aktora. Na poniższym zrzucie ekranu jest to węzeł 3. Replika podstawowa usługi obsługuje operacje odczytu i zapisu. Zmiany stanu usługi są następnie replikowane do replik pomocniczych, uruchomione na węzłach 0 i 1 na poniższym zrzucie ekranu.
W lokalizacji Węzły kliknij węzeł znaleziony w poprzednim kroku, a następnie wybierz pozycję Dezaktywuj (uruchom ponownie) z menu Akcje. Ta czynność spowoduje ponowne uruchomienie węzła w replice podstawowej usługi i wymuszenie przejścia w tryb failover do jednej z replik pomocniczych uruchomionych w innym węźle. Poziom tej repliki pomocniczej zostanie podwyższony do repliki podstawowej, inna replika pomocnicza zostanie utworzona w innym węźle oraz replika podstawowa zacznie obsługiwać operacje odczytu i zapisu. Podczas ponownego uruchamiania węzła należy zwrócić uwagę na dane wyjściowe z klienta testowego oraz to, że licznik będzie nadal się zwiększać niezależnie od trybu failover.

Usuwanie aplikacji

Użyj skryptu odinstalowania udostępnionego w szablonie, aby usunąć wystąpienie aplikacji, wyrejestrować pakiet aplikacji i usunąć pakiet aplikacji z magazynu obrazów klastra.

./uninstall.sh

W narzędziu Service Fabric Explorer aplikacja i typ aplikacji nie są już wyświetlane w węźle Aplikacje.

Biblioteki Java usługi Service Fabric w narzędziu Maven

Biblioteki Java usługi Service Fabric są teraz hostowane w narzędziu Maven. Zależności możesz dodać w pliku pom.xml lub build.gradle projektów, aby używać bibliotek Java usługi Service Fabric z repozytorium mavenCentral.

Aktorzy

Obsługa interfejsu Reliable Actors usługi Service Fabric dla Twojej aplikacji.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-actors</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-actors:1.0.0'
}

Usługi

Obsługa interfejsu Reliable Services usługi Service Fabric w Twojej aplikacji.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-services</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-services:1.0.0'
}

Inne

Transport

Obsługa warstwy transportowej dla aplikacji Java usługi Service Fabric. Nie trzeba jawnie dodawać tej zależności do aplikacji Reliable Actors lub aplikacji usługi, chyba że programujesz w warstwie transportowej.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-transport</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-transport:1.0.0'
}

Obsługa usługi Service Fabric

Obsługa na poziomie systemu dla usługi Service Fabric, która komunikuje się z natywnym środowiskiem uruchomieniowym usługi Service Fabric. Nie trzeba jawnie dodawać tej zależności do aplikacji Reliable Actors lub aplikacji usługi. Jest ona automatycznie pobierana z narzędzia Maven, kiedy uwzględnisz pozostałe powyższe zależności.

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf:1.0.0'
}