Armazenar Mensagens em Cache com Pipes Singleton

O Singleton Pipe é uma adição ao pacote DBMS_PIPE que permite armazenar em cache e recuperar uma mensagem personalizada e compartilhar a mensagem em várias sessões do banco de dados com leituras simultâneas.

Sobre Mensagens de Cache com Pipes Singleton

O pacote DBMS_PIPE tem funcionalidade estendida no Autonomous AI Database para suportar Pipes Singleton.

Um Singleton Pipe em DBMS_PIPE:

Sobre Tubos Padrão e Tubos Singleton

O Pacote DBMS_PIPE permite que duas ou mais sessões do banco de dados se comuniquem usando mensagens na memória. A funcionalidade Pipe possui vários aplicativos, como interface de serviço externo, depuração, transações independentes e alertas. Consulte DBMS_PIPE em Referência de Tipos e Pacotes PL/SQL do Oracle Database 19c ou Referência de Tipos e Pacotes PL/SQL Oracle Database 26ai para obter mais informações.

Descrição da ilustração database-pipe-messages-singleton-pipes.png

Um Singleton Pipe pode ser qualquer um dos tipos DBMS_PIPE suportados:

Os Pipes Singleton permitem armazenar em cache uma única mensagem na memória da instância do Autonomous AI Database.

O seguinte mostra o workflow geral para usar pipes singleton.

Descrição da ilustração singleton-pipe-workflow.png

Visão Geral e Recursos do Singleton Pipe

Operações de Pipe Singleton

Operação Função ou Procedimento DBMS_PIPE
Criar um Pipe Singleton Explícito Função CREATE_PIPE
Armazenar uma mensagem em cache no Singleton Pipe

PACK_MESSAGE Procedures em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference

Função SEND_MESSAGE
Ler uma mensagem em cache do Singleton Pipe Função RECEIVE_MESSAGE, Procedimentos UNPACK_MESSAGE na Referência de Tipos e Pacotes PL/SQL do Oracle Database 19c ou na Referência de Tipos e Pacotes PL/SQL do Oracle Database 26ai
Excluir uma mensagem no Singleton Pipe PURGE Procedure em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference
Remover um tubo único explícito Função REMOVE_PIPE em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference

Atualização Automática da Mensagem Armazenada em Cache com uma Função de Cache

O pacote DBMS_PIPE permite que você preencha automaticamente uma mensagem Singleton Pipe usando uma função de cache definida pelo usuário.

Por padrão, depois que uma mensagem é invalidada com a invalidação explícita ou implícita do Singleton Pipe, um DBMS_PIPE.RECEIVE_MESSAGE subsequente resulta em nenhuma mensagem sendo recebida. Para adicionar uma nova mensagem ao pipe, a mensagem deve ser armazenada no cache explicitamente chamando DBMS_PIPE.SEND_MESSAGE. Para evitar esse caso, quando nenhuma mensagem estiver disponível ao ler em um Singleton Pipe, você poderá definir uma função de cache. Com uma função de cache definida, a função de cache é chamada automaticamente quando você recebe uma mensagem nos seguintes cenários:

Para usar uma função de cache, defina a função de cache e inclua o parâmetro cache_func com DBMS_PIPE.RECEIVE_MESSAGE. Uma função de cache definida pelo usuário fornece o seguinte:

Usar uma função de cache simplifica o trabalho com Pipes Singleton. Não é necessário tratar casos de falha para receber uma mensagem de um pipe vazio. Além disso, uma função de cache garante que não haja falta de cache quando você lê mensagens de um Singleton Pipe, fornecendo o uso máximo da mensagem em cache.

Segue-se a descrição de automatic-cache-refresh-cache-function.eps

Descrição da ilustração Automatic-Cache-Refresh-Cache-function.png

Quando você define uma função de cache, o nome da função deve ser totalmente qualificado com o esquema proprietário:

Defina uma função de cache com a seguinte assinatura:

CREATE OR REPLACE FUNCTION *cache_function_name*(
       pipename  IN VARCHAR2
) RETURN INTEGER;

As operações típicas dentro de uma função de cache são:

Para usar uma função de cache, o usuário da sessão atual que chama DBMS_PIPE.RECEIVE_MESSAGE deve ter os privilégios necessários para executar a função de cache.

Consulte Função RECIEVE_MESSAGE para obter mais informações sobre como definir uma função de cache.

Criar um Pipe Singleton Explícito

Descreve as etapas para criar um Pipe Singleton com um nome de pipe especificado (um Pipe Singleton Explícito).

Primeiro, para este exemplo, crie a função auxiliar receive_message para chamar repetidamente DBMS_PIPE.RECEIVE_MESSAGE. Isso permite que você teste a funcionalidade de pipe singleton.

CREATE OR REPLACE FUNCTION msg_types AS
       TYPE t_rcv_row IS RECORD (c1 VARCHAR2(32767), c2 NUMBER);
       TYPE t_rcv_tab IS TABLE OF t_rcv_row;
END;


CREATE OR REPLACE FUNCTION receive_message(
      pipename    IN VARCHAR2,
      rcv_count   IN NUMBER DEFAULT 1,
      cache_func  IN VARCHAR2 DEFAULT NULL)
   RETURN msg_types.t_rcv_tab pipelined
    AS
       l_msg    VARCHAR2(32767);
       l_status NUMBER;
 BEGIN
      FOR i IN 1..rcv_count LOOP
           l_status := DBMS_PIPE.RECEIVE_MESSAGE(
            pipename   => pipename,
            cache_func => cache_func,
            timeout    => 1);
         IF l_status != 0 THEN
              raise_application_error(-20000,
             'Message not received for attempt: ' || to_char(i) || ' status: ' ||
            l_status);
         END IF;

         DBMS_PIPE.UNPACK_MESSAGE(l_msg);
             pipe row(msg_types.t_rcv_row(l_msg));
     END LOOP;
 RETURN;
 END;

  1. Crie um pipe singleton explícito chamado PIPE_TEST com o parâmetro shelflife definido como 3600 (segundos).

       DECLARE
   l_status INTEGER;
   BEGIN
   l_status := DBMS_PIPE.CREATE_PIPE(
                 pipename => 'MY_PIPE1',
                 private => TRUE,
                 singleton => TRUE,
                 shelflife => 3600);
   END;
   /

    Consulte Função CREATE_PIPE para obter mais informações.

  2. Verifique se o pipe singleton foi criado.

     SELECT name, singleton, type
      FROM v$db_pipes WHERE name= '&pipename' ORDER BY 1;

     NAME                 SINGLETON  TYPE

 -------------------- ---------- -------
 PIPE_TEST            YES        PRIVATE

  3. Empacote e envie uma mensagem no pipe singleton.

     EXEC DBMS_PIPE.PACK_MESSAGE('This is a real message that you can get multiple times');

 SELECT DBMS_PIPE.SEND_MESSAGE(pipename => '&pipename') status FROM DUAL;

     STATUS

 ----------
 0

    Consulte PACK_MESSAGE Procedures em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference e SEND_MESSAGE Function para obter mais informações.

  4. Receba uma mensagem de um pipe singleton.

     SELECT * FROM receive_message(
     pipename => '&pipename',
     rcv_count => 2);


     MESSAGE

 --------------------------------------------------------------------------------
 This is a real message that you can get multiple times
 This is a real message that you can get multiple times

    A função receive_message é uma função auxiliar que chama DBMS_PIPE.RECEIVE_MESSAGE.

  5. Expurgue a mensagem e remova o pipe.

     EXEC DBMS_PIPE.PURGE('&pipename');
 SELECT DBMS_PIPE.REMOVE_PIPE('&pipename') status FROM DUAL;

Criar um Pipe Singleton Explícito com uma Função de Cache

Descreve as etapas para criar um Pipe Singleton com um nome de pipe especificado, um Pipe Singleton Explícito e fornece uma função de cache. Uma função de cache permite preencher automaticamente a mensagem em um pipe singleton.

  1. Crie uma função de cache, test_cache_message, para um pipe singleton.

     CREATE OR REPLACE FUNCTION test_cache_message(
      pipename IN VARCHAR2) return NUMBER

 AS
    l_status NUMBER;
    l_data VARCHAR2(4000);
 BEGIN
    l_status := DBMS_PIPE.CREATE_PIPE(
           pipename => pipename,
           private => TRUE,
           singleton => true,
           shelflife => 600);
    IF l_status != 0 THEN RETURN l_status;
    END IF;

    DBMS_PIPE.PACK_MESSAGE('This is a placeholder cache message for an empty pipe');
    l_status := DBMS_PIPE.SEND_MESSAGE(pipename => pipename);
    RETURN l_status;
  END;
 /

    Observação: O usuário da sessão atual que chama DBMS_PIPE.RECEIVE_MESSAGE deve ter o privilégio necessário para executar a função de cache.

  2. Receber com uma função de cache e confirmar o preenchimento da mensagem no pipe. O pipe deve existir como um pipe privado criado na função de cache.

     SELECT * FROM receive_message(
      pipename => '&pipename',
      rcv_count => 1,
      cache_func => 'TEST_CACHE_MESSAGE');


     MESSAGE

 ---------------
 This is a placeholder cache message for an empty pipe

    A função receive_message é uma função auxiliar que chama DBMS_PIPE.RECEIVE_MESSAGE. Consulte Criar um Pipe Singleton Explícito para obter a definição receive_message.

    Consulte Função CREATE_PIPE para obter mais informações.

  3. Receber sem a função de cache para confirmar que a mensagem persiste no pipe.

     SELECT * FROM receive_message(
      pipename => '&pipename',
      rcv_count => 2);


     MESSAGE

 ---------------
 This is a placeholder cache message for an empty pipe
 This is a placeholder cache message for an empty pipe

    A função receive_message é uma função auxiliar que chama DBMS_PIPE.RECEIVE_MESSAGE. Consulte Criar um Pipe Singleton Explícito para obter a definição receive_message.

    Consulte Função CREATE_PIPE para obter mais informações.

Conteúdo Relacionado