APEX collection é uma estrutura temporária que se assemelha a uma tabela temporária. Os dados salvos podem ser acessados por toda a aplicação e ficam salvos ate que a sessão seja finalizada ou apagados propositalmente. Um bom exemplo de utilização é o carrinho de compras de uma loja online. Quando um usuário navega pela loja, os itens da possível compra são incluídos no carrinho e salvos temporariamente. Se o usuário desistir da compra e fechar o browser, a collection com os itens é apagada, evitando que dados salvos sem necessidade no banco de dados.
Uma collection possui a seguinte estrutura:
Não é possível inserir dados em uma collection utilizando os comandos DML, para isso é utilizado uma API do APEX chamado APEX_COLLECTION.
Criar uma Collection
Antes de utilizar a collection, precisamos inicializar ou cria-la. Para isso precisamos de um nome que não pode exceder 255 caracteres não importando se vai ter letras maiúsculas ou minúsculas. Quando a collection é criada, esse nome é convertido automaticamente para letras maiúsculas. É possível criar uma collection e depois inserir os dados ou já criar a collection informando uma consulta SQL que já vai criar a collection com os dados retornados pela consulta. No exemplo abaixo vou apenas criar a collection para depois inserir os dados.
APEX_COLLECTION.CREATE_COLLECTION(p_collection_name => 'ITENS_DO_CARRINHO');
Agora com a collection criada, podemos inserir os dados.
apex_collection.add_member(p_collection_name => 'ITENS_DO_CARRINHO',
P_C001 => 'CAMISA001',     --Cod. Produto
P_C002 => 'M',             -- Tamanho
P_C003 => 'blue001',       -- Cod. Cor
P_N001 => 1);              -- Quantidade
Se acessarmos a partir da barra de desenvolvedor do APEX a opção "Session" e selecionarmos View = Collections, podemos ver todas as collections que possuem dados na sessão atual.
Nota: Se uma collection for criada e não possuir dados, ela não vai aparecer aqui.
É importante lembrar que para acessar os dados de uma collection, é necessário esta na mesma sessão da aplicação onde inserimos os dados. Para isso basta apenas realisar uma consulta na view APEX_COLLECTIONS informando o nome como parametro.
SELECT c001, c002, c003, n001
FROM APEX_collections
WHERE collection_name = 'ITENS_DO_CARRINHO';
Se realizarmos essa consulta em uma sessão do SQL developer ou ate mesmo do SQL Commands do APEX, ela vai retornar que nenhum dado foi encontrado. Como expliquei anteriormente, precisamos estar na mesma sessão da aplicação. Felizmente é possível acessar esses dados utilizando uma PL/SQL IDE, porém, precisamos habilitar o acesso a sessão da aplicação utilizado o APEX_SESSION API, porem isso é um tema para um próximo artigo.
Alterar um registro da collection
Para alterar os dados, podemos utilizar a procedure APEX_COLLECTION.UPDATE_MEMBER, porém, essa procedure altera todas as colunas. Se quisermos alterar somente a quantidade de itens de 1 para 2, teríamos que passar todos os dados do produto novamente, alterando a quantidade. Para alterar somente a quantidade sem a necessidade incluir todos os dados desse produto novamente, podemos utilizar a APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE.
APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE (
p_collection_name => 'ITENS_DO_CARRINHO',
p_seq => 1,         -- Sequence ou ID da linha
p_attr_number => 1, --N001
p_number_value => 2); -- Quantidade modificada para 2
Note que para cada tipo de dado, alteramos o parâmetro referente ao atributo a ser alterado. Nesse caso, utilizamos p_number_value para informar que o dado que desejamos alterar e o NUMBER na posicao 1 ou seja, n001. Para alterar por exemplo, o C001, basta trocar p_number_value para p_attr_value.
Veja como alterar outros atributos aqui
Para excluir um registro/membro da collection podemos utilizar o APEX_COLLECTION.DELETE_MEMBER
p_seq => '1');
Ainda temos a opção de alterar apenas o valor de uma coluna, para isso utilizamos o mesmo conceito do UPDATE_MEMBER_ATTRIBUTE, porém, chamando APEX_COLLECTION.DELETE_MEMBER_ATTRIBUTE.
Se precisarmos apagar todos os dados da collection porem sem apagá-la, podemos utilizar o APEX_COLLECTION.TRUNCATE_COLLECTION passando o nome da collection como parâmetro. Portanto, se quisermos apagar os dados e a collection basta utilizar APEX_COLLECTION.DELETE_COLLECTION.
É possível verificar se uma collection existe utilizando APEX_COLLECTION.COLLECTION_EXISTS passando como parâmetro o nome da collection. Isso é bem útil se for executado antes de criar uma collection. Caso uma collection já exista e tentarmos criar novamente irá retornar um erro. Se quisermos saber quantos registro existem, basta executar APEX_COLLECTION.COLLECTION_MEMBER_COUNT novamente passando o nome da collection como parâmetro.
Todos os exemplos mostrados nesse artigo estão disponíveis na APEX_COLLECTION API desde a versão 4.2., ou seja independente da versão que você esteja utilizando todos vão funcionar.
Tags: apexapex collectionapioracle
maio 20, 2021 às 11:43 am
Muito boa explicaçao Rodrigo.
Next story GoldenTalks – Live com Franky Weber, Fernando Simon e Mario Barduchi (Exadata, ODA e Zero Loss na veia)