Las colecciones le permiten capturar temporalmente uno o más valores no escalares. Puede usar colecciones para almacenar filas y columnas actualmente en estado de sesión para que se pueda acceder a ellas, manipularlas o procesarlas durante la sesión específica de un usuario. Puede pensar en una colección como un cubo en el que almacena temporalmente y nombra filas de información.
Cada colección contiene una lista con nombre de elementos de datos (o miembros) que pueden tener hasta:
- 50 atributos de caracteres (VARCHAR2(4000)),
- cinco atributos de número,
- cinco atributos de fecha,
- un atributo de tipo XML,
- un atributo binario grande (BLOB) y
- un atributo de carácter grande (CLOB).
Para insertar, actualizar y eliminar la información de la colección se utiliza la API APEX_COLLECTION de PL/SQL.
Puede usar colecciones:
- Cuando está creando un asistente de entrada de datos en el que primero se deben recopilar varias filas de información dentro de una transacción lógica. Puede usar colecciones para almacenar temporalmente el contenido de varias filas de información, antes de realizar el paso final en el asistente cuando se completan las transacciones físicas y lógicas.
- Cuando su aplicación incluye una página de actualización en la que un usuario actualiza varias filas de detalles en una página. El usuario puede realizar muchas actualizaciones, aplicar estas actualizaciones a una colección y luego llamar a un proceso final para aplicar los cambios a la base de datos.
- Cuando está creando un asistente donde recopila una cantidad arbitraria de atributos. Al final del asistente, el usuario realiza una tarea que toma la información almacenada temporalmente en la colección y la aplica a la base de datos.
A partir de Oracle Database 12c, las columnas de base de datos de tipo de datos VARCHAR2 se pueden definir hasta 32 767 bytes. Esto requiere que el parámetro de inicialización de la base de datos MAX_STRING_SIZE tenga un valor de EXTENDIDO. Si Application Express se instaló en Oracle Database 12c y con MAX_STRING_SIZE = EXTENDED, las tablas para las colecciones de Application Express se definirán para admitir hasta 32 767 bytes para los atributos de caracteres de una colección. Para los métodos de la API APEX_COLLECTION, todas las referencias a atributos de caracteres (c001 a c050) pueden admitir hasta 32 767 bytes.
Al crear una colección, se le debe dar un nombre que no puede exceder los 255 caracteres. Tenga en cuenta que los nombres de las colecciones no distinguen entre mayúsculas y minúsculas y se convierten a mayúsculas.
Una vez que se nombra la colección, se puede acceder a los valores de la colección ejecutando una consulta SQL en la vista APEX_COLLECTIONS.
Se usa uno de los siguientes métodos para crear una colección:
- CREATE_COLLECTION
- CREATE_OR_TRUNCATE_COLLECTION
- CREATE_COLLECTION_FROM_QUERY
- CREATE_COLLECTION_FROM_QUERY2
- CREATE_COLLECTION_FROM_QUERY_B
- CREATE_COLLECTION_FROM_QUERYB2
Use el indicador p_generate_md5 para especificar si se debe calcular el resumen del mensaje de los datos del miembro de la colección. De forma predeterminada, este indicador está establecido en NO. Utilice este parámetro para verificar el MD5 del miembro de la colección (es decir, compararlo con otro miembro o ver si un miembro ha cambiado).
Puede acceder a los miembros de una colección consultando la vista de base de datos APEX_COLLECTIONS. Los nombres de las colecciones siempre se convierten a mayúsculas. Al consultar la vista APEX_COLLECTIONS, especifique siempre el nombre de la colección en mayúsculas. La vista APEX_COLLECTIONS tiene la siguiente definición:
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)
Use la vista APEX_COLLECTIONS en una aplicación tal como usaría cualquier otra tabla o vista en una aplicación, por ejemplo:
SELECT c001, c002, c003, n001, d001, clob001
FROM APEX_collections
WHERE collection_name = ‘DEPARTMENTS’
Puede fusionar miembros de una colección con valores pasados en un conjunto de matrices. Al utilizar el argumento p_init_query, puede crear una colección a partir de la consulta proporcionada.
Si trunca una colección, elimina todos los miembros de la colección especificada, pero la colección nombrada permanece en su lugar.
Si elimina una colección, elimina la colección y todos sus miembros. Tenga en cuenta que si no elimina una colección, eventualmente se eliminará cuando se purgue la sesión.
Puede utilizar el método DELETE_ALL_COLLECTIONS para eliminar todas las colecciones definidas en la aplicación actual.
De igual manera, puede usar el método DELETE_ALL_COLLECTIONS_SESSION para eliminar todas las colecciones definidas en la sesión actual.
Cuando se agregan elementos de datos (o miembros) a una colección, se les asigna una ID de secuencia única. A medida que agrega miembros a una colección, el ID de secuencia cambia en incrementos de 1, y los miembros más nuevos tienen el ID más grande.
Agrega nuevos miembros a una colección usando la función ADD_MEMBER. Llamar a esta función devuelve el ID de secuencia del miembro recién agregado.
También puede agregar nuevos miembros (o una matriz de miembros) a una colección mediante el procedimiento ADD_MEMBERS. La cantidad de miembros agregados se basa en la cantidad de elementos en la primera matriz.
Adicionalmente al indicador p_generate_md5 que se mencionó más arriba, puede utilizar p_clob001 para los atributos de los miembros de la colección que superen los 4000 caracteres. Utilice p_blob001 para los atributos de miembros de la colección binaria. Utilice p_xmltype001 para almacenar XML bien formado.
Puede actualizar los miembros de la colección llamando al procedimiento UPDATE_MEMBER y haciendo referencia al miembro de la colección deseado por su ID de secuencia. El procedimiento UPDATE_MEMBER reemplaza un miembro de colección completo, no atributos de miembros individuales.
Para actualizar un único atributo de un miembro de la colección, utilice el procedimiento UPDATE_MEMBER_ATTRIBUTE.
Puede eliminar un miembro de la colección llamando al procedimiento DELETE_MEMBER y haciendo referencia al miembro de la colección deseado por su ID de secuencia. Tenga en cuenta que este procedimiento deja un espacio en blanco en los ID de secuencia en la colección especificada.
También puede eliminar todos los miembros de una colección cuando un atributo coincida con un valor específico. Tenga en cuenta que el procedimiento DELETE_MEMBERS también deja un espacio en los ID de secuencia en la colección especificada. Si el valor del atributo proporcionado es nulo, se eliminan todos los miembros de la colección nombrada donde el atributo (especificado por p_attr_number) es nulo.
Utilice COLLECTION_MEMBER_COUNT para devolver el recuento total de todos los miembros de una colección. Tenga en cuenta que este recuento no indica la secuencia más alta de la colección.
Use RESEQUENCE_COLLECTION para volver a secuenciar una colección para eliminar cualquier espacio en los ID de secuencia mientras mantiene el mismo orden de elementos.
Utilice COLLECTION_EXISTS para determinar si existe una colección.
Puede ajustar el ID de secuencia de un miembro específico dentro de una colección moviendo el ID hacia arriba o hacia abajo. Cuando ajusta una ID de secuencia, la ID especificada se intercambia con otra ID. Por ejemplo, si moviera el ID 2 hacia arriba, 2 se convierte en 3 y 3 se convertiría en 2.
Utilice MOVE_MEMBER_UP para ajustar un ID de secuencia de miembro en uno. De manera alternativa, use MOVE_MEMBER_DOWN para reducir el ID de secuencia de un miembro en uno.
Utilice el método SORT_MEMBERS para reordenar los miembros de una colección por el número de columna. Este método ordena la colección por un número de columna en particular y también reasigna los ID de secuencia para que cada miembro elimine los espacios.
Borrar el estado de sesión de una colección elimina los miembros de la colección. Un carrito de compras es un buen ejemplo de cuándo podría necesitar borrar el estado de la sesión de recopilación. Cuando un usuario solicita vaciar el carrito de compras y comenzar de nuevo, debe borrar el estado de la sesión para una colección. Puede eliminar el estado de sesión de una colección llamando al método TRUNCATE_COLLECTION o usando la sintaxis f?p.
Llamar al método TRUNCATE_COLLECTION elimina la colección existente y luego la vuelve a crear, por ejemplo:
APEX_COLLECTION.TRUNCATE_COLLECTION(
p_collection_name => collection name);
También puede usar el sexto argumento de sintaxis f?p para borrar el estado de la sesión, por ejemplo:
f?p=App:Page:Session::NO:collection name
El parámetro p_generate_md5 determina si los resúmenes de mensajes MD5 se calculan para cada miembro de una colección. El indicador de estado de la colección se establece en FALSO inmediatamente después de crear una colección. Si se realiza alguna operación en la colección (como agregar, actualizar, truncar, etc.), esta marca se establece en TRUE.
Puede restablecer este indicador manualmente llamando a RESET_COLLECTION_CHANGED.
Una vez que se haya restablecido este indicador, puede determinar si una colección ha cambiado llamando a COLLECTION_HAS_CHANGED.
Cuando agrega un nuevo miembro a una colección, se calcula un resumen de mensaje MD5 contra los 50 atributos y el atributo CLOB si el parámetro p_generated_md5 se establece en YES. Puede acceder a este valor desde la columna MD5_ORIGINAL de la vista APEX_COLLECTION. Puede acceder al resumen del mensaje MD5 para el valor actual de un miembro de colección especificado mediante la función GET_MEMBER_MD5.
En la siguiente entrada, estaremos conociendo en detalle el primer grupo de procedimientos y funciones que componen el paquete APEX_COLLECTION.
