Crie seu primeiro aplicativo Java Service Fabric Reliable Actors no Linux

Este início rápido ajuda você a criar seu primeiro aplicativo Java do Azure Service Fabric em um ambiente de desenvolvimento Linux em apenas alguns minutos. Quando terminar, você terá um aplicativo Java simples de serviço único em execução no cluster de desenvolvimento local.

Pré-requisitos

Antes de começar, instale o SDK do Service Fabric, a CLI do Service Fabric, Yeoman, configure o ambiente de desenvolvimento Java e configure um cluster de desenvolvimento em seu ambiente de desenvolvimento Linux. Se você estiver usando o Mac OS X, poderá configurar um ambiente de desenvolvimento no Mac usando o Docker.

Instale também a CLI do Service Fabric.

Instalar e configurar os geradores para Java

O Service Fabric fornece ferramentas de andaimes que ajudarão você a criar um aplicativo Java do Service Fabric a partir do terminal usando o gerador de modelos Yeoman. Se o Yeoman ainda não estiver instalado, consulte Service Fabric getting started with Linux para obter instruções sobre como configurar o Yeoman. Execute o seguinte comando para instalar o gerador de modelos Yeoman do Service Fabric para Java.

npm install -g generator-azuresfjava

Conceitos básicos

Para começar a usar Reliable Actors, você só precisa entender alguns conceitos básicos:

• Serviço de atores. Os Atores Confiáveis são empacotados em Serviços Confiáveis que podem ser implantados na infraestrutura do Service Fabric. As instâncias de ator são ativadas numa instância de serviço nomeada.

• Registo de atores. Assim como acontece com os Serviços Confiáveis, um serviço de Ator Confiável precisa ser registrado no tempo de execução do Service Fabric. Além disso, o tipo de ator precisa ser registrado com o tempo de execução do ator.

• Interface do ator. A interface do ator é usada para definir uma interface pública fortemente tipada de um ator. Na terminologia do modelo Reliable Ator, a interface do ator define os tipos de mensagens que o ator pode compreender e processar. A interface do ator é usada por outros atores e aplicativos cliente para "enviar" (de forma assíncrona) mensagens para o ator. Atores confiáveis podem implementar várias interfaces.

• Classe ActorProxy. A classe ActorProxy é usada por aplicativos cliente para invocar os métodos expostos por meio da interface do ator. A classe ActorProxy fornece duas funcionalidades importantes:

  • Resolução de nome: É capaz de localizar o ator no cluster (identificar o nó do cluster onde está hospedado).
  • Tratamento de falhas: Ele pode repetir invocações de método e resolver novamente o local do ator após, por exemplo, uma falha que exija que o ator seja realocado para outro nó no cluster.

Vale a pena mencionar as seguintes regras que dizem respeito às interfaces do ator:

• Os métodos de interface dos atores não podem ser sobrecarregados.
• Os métodos de interface do ator não devem ter parâmetros out, ref ou opcionais.
• Interfaces genéricas não são suportadas.

Criar o aplicativo

Um aplicativo do Service Fabric contém um ou mais serviços, cada um com uma função específica no fornecimento da funcionalidade do aplicativo. O gerador que instalaste na última secção facilita a criação do primeiro serviço e a adicionação mais tarde. Você também pode criar, criar e implantar aplicativos Java do Service Fabric usando um plug-in para o Eclipse. Consulte Criar e implementar seu primeiro aplicativo Java usando o Eclipse. Para este início rápido, use Yeoman para criar uma aplicação com um único serviço que armazena e recupera um valor de contador.

1. Em um terminal, digite yo azuresfjava.
2. Dê um nome à aplicação.
3. Escolha o tipo do seu primeiro serviço e dê-lhe um nome. Para este tutorial, escolha um Serviço de Ator Confiável. Para obter mais informações sobre os outros tipos de serviços, consulte Visão geral do modelo de programação do Service Fabric.

Se nomeares a aplicação "HelloWorldActorApplication" e o ator "HelloWorldActor", a seguinte estrutura será criada:

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

Blocos de construção básicos de atores confiáveis

Os conceitos básicos descritos anteriormente se traduzem nos blocos de construção básicos de um serviço Reliable Ator.

Interface do ator

Isso contém a definição de interface para o ator. Esta interface define o contrato do ator que é partilhado pela implementação do ator e pelos clientes que o chamam, pelo que normalmente faz sentido defini-lo num local separado da implementação do ator e que possa ser partilhado por vários outros serviços ou aplicações cliente.

HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java:

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

    CompletableFuture<?> setCountAsync(int count);
}

Serviço de atores

Ele contém a implementação do ator e o código de registro do ator. A classe Actor implementa a interface Actor. É aqui que o seu ator faz o seu trabalho.

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

Registo de atores

O serviço de ator deve ser registado com um tipo de serviço no ambiente de execução do Service Fabric. Para que o Serviço de Ator execute suas instâncias de ator, seu tipo de ator também deve ser registrado no Serviço de Ator. O ActorRuntime método de registo realiza este trabalho para os atores.

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;
        }
    }
}

Criar o aplicativo

Os modelos do Service Fabric Yeoman incluem um script de construção para o Gradle, que você pode usar para criar o aplicativo a partir do terminal. As dependências Java do Service Fabric são buscadas no Maven. Para criar e trabalhar nos aplicativos Java do Service Fabric, você precisa garantir que o JDK e o Gradle estejam instalados. Se não estiverem instalados, consulta o Service Fabric como começar com Linux para instruções sobre como instalar o JDK e o Gradle.

Para compilar e empacotar o aplicativo, execute o seguinte:

cd HelloWorldActorApplication
gradle

Implantar o aplicativo

Depois de criada a aplicação, pode implementá-la no cluster local.

1. Conecte-se ao cluster local do Service Fabric (o cluster deve ser configurado e executado).

   sfctl cluster select --endpoint http://localhost:19080
   

2. Execute o script de instalação fornecido no modelo para copiar o pacote de aplicação para o arquivo de imagens do cluster, registar o tipo de aplicação e criar uma instância da mesma.

   ./install.sh
   

A implementação da aplicação criada é igual à de qualquer outra aplicação do Service Fabric. Veja a documentação sobre como gerir uma aplicação do Service Fabric com a CLI do Service Fabric para obter instruções detalhadas.

Os parâmetros desses comandos encontram-se nos manifestos gerados dentro do pacote de aplicação.

Depois que o aplicativo for implantado, abra um navegador e navegue até o Service Fabric Explorer em http://localhost:19080/Explorer. Depois, expanda o nó Aplicações e note que agora há uma entrada para o seu tipo de aplicação e outra para a primeira instância desse tipo.

Iniciar o cliente de teste e executar um failover

Os atores não fazem nada sozinhos. Exigem que outro serviço ou cliente lhes envie mensagens. O modelo de ator inclui um script de teste simples, que pode utilizar para interagir com o serviço de ator.

1. Execute o script com o utilitário watch para ver o resultado do serviço de ator. O script de teste chama o setCountAsync() método no ator para incrementar um contador, chama o getCountAsync() método no ator para obter o novo valor do contador e exibe esse valor no console.

   No macOS X, é necessário copiar a pasta HelloWorldTestClient para um local dentro do contentor executando os seguintes comandos adicionais.

    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
   

2. No Service Fabric Explorer, localize o nó que hospeda a réplica primária do serviço ator. Na captura de ecrã abaixo, é o nó 3. A réplica do serviço principal lida com operações de leitura e gravação. As alterações no estado do serviço são replicadas para as réplicas secundárias, sendo executadas nos nós 0 e 1 na captura de tela abaixo.

   

3. Nos Nodes, selecionar o nó que encontraste no passo anterior, e depois selecionar Desativar (reiniciar) do menu Ações. Esta ação reinicia o nó que executa a réplica primária do serviço e força um processo de failover para uma das réplicas secundárias que estão em execução em outro nó. Essa réplica secundária é promovida a primária, outra réplica secundária é criada num nó diferente, e a réplica primária começa a realizar operações de leitura/escrita. À medida que o nó é reiniciado, observe a saída do cliente de teste e observe que o contador continua a aumentar apesar do failover.

Remover o aplicativo

Use o script de desinstalação fornecido no modelo para excluir a instância do aplicativo, cancelar o registro do pacote do aplicativo e remover o pacote do aplicativo do armazenamento de imagens do cluster.

./uninstall.sh

No explorador do Service Fabric, você vê que o aplicativo e o tipo de aplicativo não aparecem mais no nó Aplicativos .

Bibliotecas Java do Service Fabric no Maven

As bibliotecas Java do Service Fabric foram alojadas no Maven. Pode adicionar as dependências no pom.xml ou build.gradle dos seus projetos para utilizar bibliotecas Java do Service Fabric a partir de mavenCentral.

Atores

Suporte de Reliable Actor do Service Fabric para a sua aplicação.

<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'
}

Serviços

Suporte do Service Fabric Reliable Services para seu aplicativo.

<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'
}

Outros

Transportes

Suporte da camada de transporte para a aplicação Java do Service Fabric. Não precisa de adicionar explicitamente esta dependência às suas aplicações Reliable Actor ou Service, a menos que programe na camada de transporte.

<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'
}

Suporte de Fabric

Suporte ao nível do sistema para o Service Fabric, que se comunica com o runtime nativo do Service Fabric. Não precisa de adicionar explicitamente esta dependência às suas aplicações Reliable Actor ou Service. Isto é obtido automaticamente do Maven, quando incluir as outras dependências acima.

<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'
}

Próximos passos

• Crie seu primeiro aplicativo Java do Service Fabric no Linux usando o Eclipse
• Saiba mais sobre Reliable Actors
• Interagir com os clusters do Service Fabric através da CLI do Service Fabric
• Saiba mais sobre as opções de suporte do Service Fabric
• Introdução à CLI do Service Fabric