Zipping and unzipping

ADM can pack a document or an entire folder tree into a .zip, and expand an uploaded .zip back into folders and documents.

The archive is an ADM document

The archive produced is a real ADM document: it lands in a folder, it is versioned, audited, permission-checked, and subject to that folder’s storage policy like any other file. Selecting a few files in the browser and downloading them is a different operation: it streams a zip to the browser and stores nothing.

Zipping

One document

declare
  l_zip_id number;
begin
  adm_context_api.system_user_login('JDOE');

  l_zip_id := adm_zip_api.zip_document(
    p_document_id => l_document_id
  );

  commit;
end;
/

The archive is named after the document with the extension replaced — report.pdf becomes report.zip — and holds one entry under the document’s own name. It is created in the document’s own folder unless you pass p_target_folder_id, and you need edit rights on wherever it is created.

A folder tree

l_zip_id := adm_zip_api.zip_folder(
  p_folder_id        => l_folder_id
, p_target_folder_id => l_target_folder_id   -- defaults to the folder's parent
);

The archive lands next to the folder, in its parent, the way a desktop file manager does it — not inside the folder it is a copy of. Two cases keep the archive in the folder itself, because there is nowhere beside it to put one: the repository root, which has no parent, and a home folder, whose parent is the system folder /users that its owner may read but not write. An explicit p_target_folder_id overrules all of it, and you need edit rights on wherever the archive is created.

Entry paths are relative to the folder you zipped, so a document in child/grandchild ends up at child/grandchild/report.pdf — not under the folder’s absolute path.

Skipped without an error: trashed subfolders, trashed documents, archived documents, and anything the caller may not view. The read side runs under the caller’s own permissions, so two users zipping the same folder can legitimately get different archives. If nothing readable is found at all, the call fails rather than producing an empty archive.

Nothing is ever overwritten. Zipping the same folder twice gives you projects.zip and then projects_restored.zip.

Unzipping

declare
  l_folder_id number;
begin
  adm_context_api.system_user_login('JDOE');

  l_folder_id := adm_zip_api.unzip_document(
    p_document_id => l_zip_document_id
  );

  commit;    -- see the transaction note below
end;
/

A folder named after the archive is created next to it, and the structure inside is recreated below it. Three behaviours:

• A redundant top-level directory is dropped. If every entry sits under one common directory — which is what desktop zip tools produce — you get projects/..., not projects/projects/....
• Existing folders are reused, not duplicated. A document name that is already taken gets a free one rather than overwriting.
• Unsafe entry paths fail the whole call. An absolute path, a drive letter or any .. segment is rejected outright rather than sanitised: a sanitised path would silently write somewhere the archive did not name.

Limits

Guard	Value
Entries per archive	5,000
Total uncompressed size	2 GiB
Size of a produced archive	2 GiB

These are constants in adm_zip_api, not rows in adm_settings: they bound what one call can do to shared storage. Any user with edit rights can unzip, so a crafted archive that decompresses to hundreds of times its own size must not be able to fill your tablespace. unzip_document accepts p_max_entries and p_max_extracted_bytes if you want to be stricter for a particular call.

The extracted-size guard is checked before anything is written, so an archive that is too large fails without leaving a half-expanded tree behind.

You own the transaction — including the rollback

adm_zip_api never commits and never rolls back. If unzip_document trips a guard part way through, the caller has to roll back; the partial tree is otherwise still in your transaction. Nothing is visible to other sessions until you commit.

begin
  l_folder_id := adm_zip_api.unzip_document(p_document_id => l_zip_id);
  commit;
exception
  when others then
    rollback;
    raise;
end;
/

Errors

All of these are raised as named exceptions on adm_error — see Error handling.

Situation	Error
The document is not a zip file	c_err_not_an_archive
The archive holds no files, or the folder had nothing readable	c_err_archive_empty
An entry path is absolute or contains ..	c_err_invalid_name
Any guard exceeded	c_err_limit_exceeded
No rights on the source, or on the destination folder	c_err_no_view_right, c_err_no_edit_right
The target is the trash folder	c_err_folder_trash_rule

Also refer to

• Working with documents
• Managing the filesystem from the database
• adm_zip_api