Coleções APEX para gerenciar dados temporários

A coleção APEX é uma estrutura temporária, semelhante a uma tabela temporária. Os dados armazenados nele podem ser acessados ​​por meio do aplicativo e são retidos até que a sessão termine ou sejam excluídos intencionalmente. Um excelente exemplo de seu uso é o recurso de carrinho de compras em uma loja online. 

À medida que o usuário navega na loja, as compras potenciais são adicionadas ao carrinho e armazenadas temporariamente. Caso o usuário abandone a compra e feche o navegador, a coleção que contém os itens é excluída, evitando armazenamento desnecessário de dados no banco de dados.

COLLECTION_NAME   NOT NULL VARCHAR2(255)
SEQ_ID            NOT NULL NUMBER 
C001              VARCHAR2(4000)
C002              VARCHAR2(4000)
C003              VARCHAR2(4000)   
C004              VARCHAR2(4000)   
C005              VARCHAR2(4000)  
...
C050              VARCHAR2(4000)
N001              NUMBER
N002              NUMBER
N003              NUMBER
N004              NUMBER
N005              NUMBER     
D001              DATE
D002              DATE
D003              DATE
D004              DATE
D005              DATE
CLOB001           CLOB
BLOB001           BLOB  
XMLTYPE001        XMLTYPE
MD5_ORIGINAL      VARCHAR2(4000) 

Não é possível inserir dados em uma coleção utilizando comandos DML; em vez disso, uma API chamada APEX_COLLECTION é usada.

Crie uma coleção

Antes de usar uma coleção, devemos inicializá-la ou criá-la. Para isso, precisamos de um nome que não possa ultrapassar 255 caracteres, independentemente de conter letras maiúsculas ou minúsculas. Quando a coleção é criada, esse nome é automaticamente convertido para letras maiúsculas. É possível criar uma coleção e depois inserir os dados, ou criar a coleção fornecendo uma consulta SQL que irá gerar a coleção com os dados retornados pela consulta. No exemplo abaixo, simplesmente criarei a coleção e depois inserirei os dados.

BEGIN
 APEX_COLLECTION.CREATE_COLLECTION(p_collection_name => 'SHOPPING_CART');
END;

Agora que a coleção foi criada, podemos prosseguir com a inserção dos dados.

BEGIN
  apex_collection.add_member(p_collection_name => 'SHOPPING_CART',
                             P_C001 => 'SHIRT001', -- product code
                             P_C002 => 'M', -- Size
                             P_C003 => 'blue001', -- color code
                             P_N001 => 1); -- Amount
END;

Se acessarmos a opção “Sessão” da barra do desenvolvedor APEX e selecionarmos Visualizar = Coleções, podemos ver todas as coleções que possuem dados na sessão atual.

Nota: Se uma coleção for criada e não tiver dados, ela não aparecerá aqui.

É importante lembrar que para acessar os dados de uma coleção é necessário estar na mesma sessão da aplicação onde os dados foram inseridos. Para isso, basta executar uma consulta na view APEX_COLLECTIONS, fornecendo o nome como parâmetro.

SELECT c001, c002, c003, n001
FROM APEX_collections
WHERE collection_name = 'SHOPPING_CART';

Se executarmos esta consulta em uma sessão SQL Developer ou mesmo em APEX SQL Commands, ela não retornará nenhum dado encontrado. Conforme mencionado anteriormente, precisamos estar na mesma sessão do aplicativo.

Alterar um registro de coleção

Para modificar os dados, podemos usar o procedimento APEX_COLLECTION.UPDATE_MEMBER; no entanto, este procedimento altera todas as colunas. Se desejarmos apenas alterar o número de itens de 1 para 2, precisaremos reenviar todos os dados do produto enquanto ajustamos a quantidade. Para atualizar apenas a quantidade sem precisar fornecer todos os dados daquele produto novamente, podemos usar a API APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE.

BEGIN
      APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE (
          p_collection_name => 'SHOPPING_CART',
          p_seq => 1, -- Sequence or Line ID
          p_attr_number => 1, -- N001
          p_number_value => 2); -- Quantity modified to 2
END;

Observe que para cada tipo de dado alteramos o parâmetro referente ao atributo que necessita de modificação. Neste caso, usamos p_number_value para indicar que o dado que queremos alterar é o NÚMERO na posição 1, que é n001. Para modificar, por exemplo, C001, basta alterar p_number_value para p_attr_value.

Excluir um registro

Para deletar um registro/membro da coleção podemos usar APEX_COLLECTION.DELETE_MEMBER

BEGIN
      APEX_COLLECTION.DELETE_MEMBER(
          p_collection_name => 'SHOPPING_CART',
          p_seq => '1');
END;

Ainda temos a opção de alterar apenas o valor de uma coluna. Para fazer isso, usamos o mesmo conceito de UPDATE_MEMBER_ATTRIBUTE, mas chamamos APEX_COLLECTION.DELETE_MEMBER_ATTRIBUTE.

Se precisarmos deletar todos os dados da coleção sem deletar a coleção em si, podemos usar APEX_COLLECTION.TRUNCATE_COLLECTION, passando o nome da coleção como parâmetro. Se quisermos deletar os dados e a coleção, simplesmente usamos APEX_COLLECTION.DELETE_COLLECTION.

É possível verificar se existe uma coleção usando APEX_COLLECTION.COLLECTION_EXISTS e passando o nome da coleção como parâmetro. Isto é muito útil se executado antes de criar uma coleção. Se já existir uma coleção e tentarmos criá-la novamente, um erro será retornado. Se quisermos saber quantos registros existem, basta executar novamente APEX_COLLECTION.COLLECTION_MEMBER_COUNT, passando o nome da coleção como parâmetro.

Todos os exemplos apresentados neste blog são compatíveis com a API APEX_COLLECTION a partir da versão 4.2. Isso significa que, independentemente da versão que você estiver usando, todas funcionarão corretamente.

----

Fonte: Rodrigo Mesquita - APEX BLOG