adm_zip_api

Packs a document or a whole folder tree into a stored .zip document, and expands a stored .zip document back into a folder tree.

The archive it produces is a real ADM document, so it is versioned, audited, permission-checked and subject to the target folder’s object storage policy like any other upload. Streaming a multi-file download to the browser is a different job and is already covered by the UNITEDCODES_DOWNLOAD_FILES_DA plugin in the app - do not route that through here.

Everything runs under the caller’s permissions, read side included. zip_folder walks the subtree and then asks adm_access_control_api.user_is_allowed_to_view_document for every document it finds, rather than joining adm_user_accessible_documents_mcr: the macro has no administrator bypass, so an admin zipping a folder they do not own would silently get fewer files than they can see.

Trashed and archived content is never included, and nothing is ever overwritten. A name that is already taken gets a free one via adm_document_api.get_free_document_name, so zipping the same folder twice produces projects.zip and then projects_restored.zip.

No commit and no rollback - the caller owns the transaction. That also means the caller has to roll back if unzip_document trips a size guard part way through, and that the extracted tree is not visible to other sessions until the caller commits.

Functions and Procedures

zip_document

Packs one document into a new .zip document.

The archive is named after the document with its extension replaced, so report.pdf produces report.zip, and it holds a single entry under the document’s own name.

Raises adm_error.c_err_doc_not_found when the document does not exist or is in the trash, adm_error.c_err_no_current_version when it has no version to read, adm_error.c_err_no_view_right when the caller may not read it, and adm_error.c_err_limit_exceeded when the result would be larger than c_max_archive_bytes.

Signature:

function zip_document (
  p_document_id in adm_documents.document_id%type,
  p_target_folder_id in adm_folders.folder_id%type default null
) return adm_documents.document_id%type;

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type	The document to pack
p_target_folder_id	in	adm_folders.folder_id%type default null	Where the archive is created; defaults to the document’s own

                      folder. EDIT rights on it are required. |

Returns: adm_documents.document_id%type - The document id of the new archive

---

zip_folder

Packs a folder and everything below it into a new .zip document.

Entry paths are relative to the folder itself, so a document in child/grandchild ends up at child/grandchild/report.pdf rather than carrying the folder’s absolute path. Trashed subfolders, trashed documents, archived documents and documents the caller may not view are all skipped without failing the call.

Raises adm_error.c_err_folder_not_found when the folder does not exist or is in the trash, adm_error.c_err_no_view_right when the caller may not see it, adm_error.c_err_folder_trash_rule for the trash folder itself, adm_error.c_err_archive_empty when nothing readable was found, and adm_error.c_err_limit_exceeded past c_max_archive_bytes.

Signature:

function zip_folder (
  p_folder_id in adm_folders.folder_id%type,
  p_target_folder_id in adm_folders.folder_id%type default null
) return adm_documents.document_id%type;

Parameters:

Name	Direction	Type	Description
p_folder_id	in	adm_folders.folder_id%type	The folder to pack
p_target_folder_id	in	adm_folders.folder_id%type default null	Where the archive is created; defaults to the folder’s parent

Returns: adm_documents.document_id%type - The document id of the new archive

---

unzip_document

Expands a stored .zip document into a new folder tree next to it.

A folder named after the archive is created in the archive’s own folder, and the structure inside the archive is recreated below it. When every entry sits under one common top level directory that directory is dropped, so an archive built by a desktop tool does not produce projects/projects/… A folder that already exists is reused rather than duplicated, and a document name that is taken gets a free one.

Entry paths are validated before anything is written. An absolute path, a drive letter or any ’..’ segment fails the whole call with adm_error.c_err_invalid_name rather than being sanitised, because an archive containing one is not a mistake.

Raises adm_error.c_err_doc_not_found, adm_error.c_err_no_current_version, adm_error.c_err_no_view_right, adm_error.c_err_no_edit_right on the destination, adm_error.c_err_folder_trash_rule, adm_error.c_err_not_an_archive when the document is not a zip file, adm_error.c_err_archive_empty when it holds no files, adm_error.c_err_invalid_name for an unsafe entry path, adm_error.c_err_folder_exists when a trashed folder holds a name the tree needs, and adm_error.c_err_limit_exceeded past any of the guards.

Signature:

function unzip_document (
  p_document_id in adm_documents.document_id%type,
  p_max_entries in pls_integer default c_max_entries,
  p_max_extracted_bytes in number default c_max_extracted_bytes
) return adm_folders.folder_id%type;

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type	The .zip document to expand
p_max_entries	in	pls_integer default c_max_entries	Refuse an archive with more entries than this. Exposed so

                         a stricter policy, or a test, can lower it. |

| p_max_extracted_bytes | in | number default c_max_extracted_bytes | Refuse an archive whose entries add up to more than this uncompressed. Checked before anything is written. |

Returns: adm_folders.folder_id%type - The folder id of the archive’s root folder

---