adm_utils

This document contains the API documentation for the adm_utils package.

Functions and Procedures

escape_like

Escapes the LIKE wildcards in a literal so it can be used as a fixed prefix in a LIKE pattern. The pattern has to carry escape '\'.

Folder and document names may contain _ and %, and both are LIKE wildcards. A subtree query written as folder_path like l_path || '/%' therefore also matches siblings of the target: with l_path = ‘/users/bob/my_docs’ it matches ‘/users/bob/myxdocs/sub’ as well. That is how a rename, move, trash, restore or permanent delete of one folder can rewrite or destroy another folder’s subtree.

Signature:

function escape_like (
  p_text in varchar2
) return varchar2 deterministic;

Parameters:

Name	Direction	Type	Description
p_text	in	varchar2	The literal to be used as a LIKE prefix

Returns: varchar2 deterministic - The literal with , _ and % escaped for escape '\'

---

path_user_owner

Derives adm_documents.user_owner from the path of the folder a document sits in.

Returns the upper-cased first segment below /users, or null when the path is not under /users at all. It is the single definition of that rule: both the adm_documents_biu trigger and adm_folder_api.move_folder call it, so a document that changes folder and a document that is inserted derive their owner the same way.

Signature:

function path_user_owner (
  p_folder_path in adm_folders.folder_path%type
) return varchar2 deterministic;

Parameters:

Name	Direction	Type	Description
p_folder_path	in	adm_folders.folder_path%type	Path of the folder holding the document

Returns: varchar2 deterministic - Upper-cased owning username, or null

---

path_group_owner

Derives adm_documents.group_owner from the path of the folder a document sits in. The /groups counterpart of [path_user_owner].

Signature:

function path_group_owner (
  p_folder_path in adm_folders.folder_path%type
) return varchar2 deterministic;

Parameters:

Name	Direction	Type	Description
p_folder_path	in	adm_folders.folder_path%type	Path of the folder holding the document

Returns: varchar2 deterministic - Upper-cased owning group folder name, or null

---

assert_valid_name

Raises adm_error.c_err_invalid_name when a document or folder name contains a character that has no business being in one.

Rejected are the control characters and the set every desktop operating system reserves anyway: < > : ” / \ | ? *. Blocking them at the write path is what keeps a name out of trouble downstream, where it is rendered into HTML, put into a Content-Disposition header and used to build folder paths. Characters that are legal in a filename and merely need escaping when rendered - space & ’ ( ) % _ and the like - are allowed. An internal space is legal in both a document name and a folder name; a leading or trailing one is not, because it is invisible.

Signature:

procedure assert_valid_name (
  p_name in varchar2,
  p_what in varchar2 default 'Name',
  p_allow_colon in boolean default true,
  p_max_length in pls_integer default 255
);

Parameters:

Name	Direction	Type	Description
p_name	in	varchar2	The name to check
p_what	in	varchar2 default 'Name'	What is being named, for the error message (‘Document’, ‘Folder’)
p_allow_colon	in	boolean default true	-
p_max_length	in	pls_integer default 255	-

---

assert_valid_username

Raises adm_error.c_err_invalid_username when a username contains a character that has no business being in one. Usernames end up inside the LIKE patterns that decide access (‘/users//%’), so ’%’ in particular must never get in; note that ’_’ is a LIKE wildcard too but far too common in usernames to reject, which is what escape_like is for.

Signature:

procedure assert_valid_username (
  p_username in varchar2
);

Parameters:

Name	Direction	Type	Description
p_username	in	varchar2	The username to check

---

sanitize_text_query

Turns free text into a safe Oracle Text query expression.

A search term is passed to contains() as a query, not as a literal: characters like { } & | ~ $ ! ( ) , and the operators NEAR, ACCUM and ABOUT are all live, so a raw term either changes the meaning of the search or raises DRG-509xx. Every token is therefore reduced to alphanumerics and wrapped in braces, and the tokens are combined with ACCUM so that a multi-word search returns something instead of failing.

Signature:

function sanitize_text_query (
  p_query in varchar2
) return varchar2;

Parameters:

Name	Direction	Type	Description
p_query	in	varchar2	The raw search term as the user typed it

Returns: varchar2 - An Oracle Text expression, or NULL when nothing usable is left

---