adm_folder_api

This document contains the API documentation for the adm_folder_api package.

Functions and Procedures

is_trash_folder

True when the folder is a user’s trash folder.

The trash folder is itself deleted_flag = ‘N’ - it is a live system folder that holds the trashed subtrees - so the “is the target in the trash?” guards elsewhere do not catch it. Anything that creates or moves a live row into a folder has to ask this as well, or it produces a live row sitting in the trash: invisible in the listings, refused by restore (it is not deleted) and refused by the permanent delete (same), i.e. stuck there for good.

Signature:

function is_trash_folder (
  p_folder_id in adm_folders.folder_id%type
) return boolean;

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The folder to check

Returns: boolean - true if this is a /users//trash folder

get_folder_id

Retrieves a folder ID based on the folder path Throws an exception if the folder does not exist.

Signature:

function get_folder_id (
  p_folder_path in adm_folders.folder_path%type
) return adm_folders.folder_id%type;

Parameters:

Name	Direction	Type	Description
`p_folder_path`	in	`adm_folders.folder_path%type`	The path of the folder to find

Returns: adm_folders.folder_id%type - The ID of the folder matching the given path

add_folder

Creates a new folder and returns its ID

Signature:

function add_folder (
  p_folder_name in adm_folders.folder_name%type,
  p_parent_folder_id in adm_folders.parent_folder_id%type,
  p_is_system_folder in adm_folders.is_system_folder%type default 'N'
) return adm_folders.folder_id%type;

Parameters:

Name	Direction	Type	Description
`p_folder_name`	in	`adm_folders.folder_name%type`	The name of the new folder
`p_parent_folder_id`	in	`adm_folders.parent_folder_id%type`	The ID of the parent folder
`p_is_system_folder`	in	`adm_folders.is_system_folder%type default 'N'`	Flag indicating if this is a system folder (defaults to ‘N’)

Returns: adm_folders.folder_id%type - The ID of the newly created folder

add_folder

Creates a new folder (procedure version)

Signature:

procedure add_folder (
  p_folder_name in adm_folders.folder_name%type,
  p_parent_folder_id in adm_folders.parent_folder_id%type,
  p_is_system_folder in adm_folders.is_system_folder%type default 'N'
);

Parameters:

Name	Direction	Type	Description
`p_folder_name`	in	`adm_folders.folder_name%type`	The name of the new folder
`p_parent_folder_id`	in	`adm_folders.parent_folder_id%type`	The ID of the parent folder
`p_is_system_folder`	in	`adm_folders.is_system_folder%type default 'N'`	Flag indicating if this is a system folder (defaults to ‘N’)

rename_folder

Renames an existing folder

Signature:

procedure rename_folder (
  p_folder_id in adm_folders.folder_id%type,
  p_new_folder_name in adm_folders.folder_name%type
);

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The ID of the folder to be renamed
`p_new_folder_name`	in	`adm_folders.folder_name%type`	The new name for the folder

move_folder

Moves a folder to a new parent folder

Signature:

procedure move_folder (
  p_folder_id in adm_folders.folder_id%type,
  p_new_parent_folder_id in adm_folders.parent_folder_id%type
);

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The ID of the folder to be moved
`p_new_parent_folder_id`	in	`adm_folders.parent_folder_id%type`	The ID of the new parent folder

trash_folder

Moves a folder to the user’s trash folder.

The whole subtree goes with it: every descendant folder and every document below gets deleted_flag = ‘Y’, so deleted_flag means “is in the trash” everywhere. Only this folder gets trash_root_flag = ‘Y’ and remembers its original parent, which makes it the only row in the subtree that can be restored.

Signature:

procedure trash_folder (
  p_folder_id in adm_folders.folder_id%type,
  p_user_id in varchar2
);

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The ID of the folder to be moved to trash
`p_user_id`	in	`varchar2`	The ID of the user who is trashing the folder

restore_folder

Restores a folder from the trash to its original location, together with its whole subtree.

Only a trash root can be restored. Restoring a folder that merely fell into the trash with an ancestor raises adm_error.c_err_folder_trash_rule; so does restoring into a location that is itself in the trash.

Signature:

procedure restore_folder (
  p_folder_id in adm_folders.folder_id%type
);

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The ID of the folder in trash to be restored

permanently_delete_folder

Permanently deletes a folder from the trash, including its whole subtree. Call trash_folder first to move the folder to trash.

Documents are removed through adm_document_api.permanently_delete_document, so stored file content, tags and shares are cleaned up too. Raises adm_error.c_err_folder_has_protected if any document in the subtree is under legal hold or a retention policy; nothing is deleted in that case.

Signature:

procedure permanently_delete_folder (
  p_folder_id in adm_folders.folder_id%type
);

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The ID of the folder to be permanently deleted

create_trash_folder

Creates a trash folder for a specific user

Signature:

function create_trash_folder (
  p_username in varchar2
) return adm_folders.folder_id%type;

Parameters:

Name	Direction	Type	Description
`p_username`	in	`varchar2`	The username for which to create the trash folder

Returns: adm_folders.folder_id%type - The ID of the newly created trash folder

is_parent_folder

Checks if a folder is a parent of another folder

Signature:

function is_parent_folder (
  p_potential_parent_id in number,
  p_potential_child_id in number
) return boolean;

Parameters:

Name	Direction	Type	Description
`p_potential_parent_id`	in	`number`	The ID of the potential parent folder
`p_potential_child_id`	in	`number`	The ID of the potential child folder

Returns: boolean - True if the potential parent is a parent of the potential child, false otherwise