I’ve been working on a flexible table API generator for Oracle Databases since several months. A TAPI generator doesn’t sound like a real innovation. But this one contains some features you probably have not seen before in TAPI generator and hopefully will like it as much as I do.
In this post I will not explain the feature set thoroughly. Instead I will more or less focus on one of my favourite features.
Four models
The generators knows the following four data models.
If your table is based on one of these four models you may
- simply generate a table API for it or
- switch to another model and optionally generate a table API as well.
Option 2) is extraordinary, since it will preserve the existing data. E.g. it will preserve the content of the flashback data archive when you switch your model from uni-temporal transaction-time to a bi-temporal model even if the flashback archive tables need to be moved to another table. Furthermore it will keep the interface for the latest table the same. No application change required. Everything with just a few mouse clicks. If this sounds interesting for you, then have a look at https://github.com/oddgen/bitemp/blob/master/README.md where the concept is briefly explained or join me my session “oddgen – Bi-temporal Table API in Action” at the More than just – Performance Days 2016. Remote participation is still possible.
Option 1) is what we had since years. It was part of Oracle Designer, it’s part of SQL Developer in a simplified way and there are a some more or less simple table API generators around. So no big deal. However, when you choose option 1), there is one part which is really cool. The hook API package concept.
The Hook API
The problem with a lot of table API solution is, that there is typically no developer friendly way to include the business logic. I’ve seen the following:
- Manual changes of the generated code, which is for various reason not a good solution.
- External hooks, e.g. in XML files, in INI files, relational tables, etc. and merged at generation time into the final code. Oracle Designer worked that way.
- Code which is dynamically executed by the generator at runtime, e.g. code snippets are stored in an pre-defined way in relational tables.
But what I’ve never seen, was business logic implemented in manually crafted PL/SQL packages, separated from the PL/SQL generated code. That’s strange, because this is a common practice in Java based projects.
In Java you typically define an interface for that and configure at runtime the right implementation. In PL/SQL we may do that similarly. A PL/SQL specification is an interface definition. That just one implementation may exist for an interface is not a limiting factor in this case.
Bitemp Remodeler generates the following hook API package specification for the famous EMP table in schema SCOTT:
CREATE OR REPLACE PACKAGE emp_hook AS
/**
* Hooks called by non-temporal API for table emp_lt (see package body of emp_api)
* generated by Bitemp Remodeler for SQL Developer.
* The body of this package is not generated. It has to be crafted and maintained manually.
* Since the API for table emp_lt ignores errors caused by a missing hook package body, the implementation is optional.
*
* @headcom
*/
/**
* Hook called before insert into non-temporal table emp_lt.
*
* @param io_new_row new Row to be inserted
*/
PROCEDURE pre_ins (
io_new_row IN OUT emp_ot
);
/**
* Hook called after insert into non-temporal table emp_lt.
*
* @param in_new_row new Row to be inserted
*/
PROCEDURE post_ins (
in_new_row IN emp_ot
);
/**
* Hook called before update non-temporal table emp_lt.
*
* @param io_new_row Row with updated column values
* @param in_old_row Row with original column values
*/
PROCEDURE pre_upd (
io_new_row IN OUT emp_ot,
in_old_row IN emp_ot
);
/**
* Hook called after update non-temporal table emp_lt.
*
* @param in_new_row Row with updated column values
* @param in_old_row Row with original column values
*/
PROCEDURE post_upd (
in_new_row IN emp_ot,
in_old_row IN emp_ot
);
/**
* Hook called before delete from non-temporal table emp_lt.
*
* @param in_old_row Row with original column values
*/
PROCEDURE pre_del (
in_old_row IN emp_ot
);
/**
* Hook called after delete from non-temporal table emp_lt.
*
* @param in_old_row Row with original column values
*/
PROCEDURE post_del (
in_old_row IN emp_ot
);
END emp_hook;
/The generated table API calls before an INSERT the pre_ins procedure and after the INSERT the post_ins procedures. For DELETE and UPDATE this works the same way. On the highlighted line 5 and 6 two interested things are pointed out. The body is not generated and the body does not need to be implemented since the API ignores errors caused by a missing PL/SQL hook package body.
Technically this is solved as follows in the API package body:
CREATE OR REPLACE PACKAGE BODY emp_api AS
--
-- Note: SQL Developer 4.1.3 cannot produce a complete outline of this package body, because it cannot handle
-- the complete flashback_query_clause. The following expression breaks SQL Developer:
--
-- VERSIONS PERIOD FOR vt$ BETWEEN MINVALUE AND MAXVALUE
--
-- It's expected that future versions will be able to handle the flashback_query_clause accordingly.
-- See "Bug 24608738 - OUTLINE OF PL/SQL PACKAGE BODY BREAKS WHEN USING PERIOD FOR OF FLASHBACK_QUERY_"
-- on MOS for details.
--
--
-- Declarations to handle 'ORA-06508: PL/SQL: could not find program unit being called: "SCOTT.EMP_HOOK"'
--
e_hook_body_missing EXCEPTION;
PRAGMA exception_init(e_hook_body_missing, -6508);
--
-- Debugging output level
--
g_debug_output_level dbms_output_level_type := co_off;
--
-- print_line
--
PROCEDURE print_line (
in_proc IN VARCHAR2,
in_level IN dbms_output_level_type,
in_line IN VARCHAR2
) IS
BEGIN
IF in_level <= g_debug_output_level THEN
sys.dbms_output.put(to_char(systimestamp, 'HH24:MI:SS.FF6'));
CASE in_level
WHEN co_info THEN
sys.dbms_output.put(' INFO ');
WHEN co_debug THEN
sys.dbms_output.put(' DEBUG ');
ELSE
sys.dbms_output.put(' TRACE ');
END CASE;
sys.dbms_output.put(substr(rpad(in_proc,27), 1, 27) || ' ');
sys.dbms_output.put_line(substr(in_line, 1, 250));
END IF;
END print_line;
--
-- print_lines
--
PROCEDURE print_lines (
in_proc IN VARCHAR2,
in_level IN dbms_output_level_type,
in_lines IN CLOB
) IS
BEGIN
IF in_level <= g_debug_output_level THEN
<<all_lines>>
FOR r_line IN (
SELECT regexp_substr(in_lines, '[^' || chr(10) || ']+', 1, level) AS line
FROM dual
CONNECT BY instr(in_lines, chr(10), 1, level - 1) BETWEEN 1 AND length(in_lines) - 1
) LOOP
print_line(in_proc => in_proc, in_level => in_level, in_line => r_line.line);
END LOOP all_lines;
END IF;
END print_lines;
--
-- do_ins
--
PROCEDURE do_ins (
io_row IN OUT emp_ot
) IS
BEGIN
INSERT INTO emp_lt (
empno,
ename,
job,
mgr,
hiredate,
sal,
comm,
deptno
)
VALUES (
io_row.empno,
io_row.ename,
io_row.job,
io_row.mgr,
io_row.hiredate,
io_row.sal,
io_row.comm,
io_row.deptno
)
RETURNING empno
INTO io_row.empno;
print_line(
in_proc => 'do_ins',
in_level => co_debug,
in_line => SQL%ROWCOUNT || ' rows inserted.'
);
END do_ins;
--
-- do_upd
--
PROCEDURE do_upd (
io_new_row IN OUT emp_ot,
in_old_row IN emp_ot
) IS
BEGIN
UPDATE emp_lt
SET empno = io_new_row.empno,
ename = io_new_row.ename,
job = io_new_row.job,
mgr = io_new_row.mgr,
hiredate = io_new_row.hiredate,
sal = io_new_row.sal,
comm = io_new_row.comm,
deptno = io_new_row.deptno
WHERE empno = in_old_row.empno
AND (
(ename != io_new_row.ename OR ename IS NULL AND io_new_row.ename IS NOT NULL OR ename IS NOT NULL AND io_new_row.ename IS NULL) OR
(job != io_new_row.job OR job IS NULL AND io_new_row.job IS NOT NULL OR job IS NOT NULL AND io_new_row.job IS NULL) OR
(mgr != io_new_row.mgr OR mgr IS NULL AND io_new_row.mgr IS NOT NULL OR mgr IS NOT NULL AND io_new_row.mgr IS NULL) OR
(hiredate != io_new_row.hiredate OR hiredate IS NULL AND io_new_row.hiredate IS NOT NULL OR hiredate IS NOT NULL AND io_new_row.hiredate IS NULL) OR
(sal != io_new_row.sal OR sal IS NULL AND io_new_row.sal IS NOT NULL OR sal IS NOT NULL AND io_new_row.sal IS NULL) OR
(comm != io_new_row.comm OR comm IS NULL AND io_new_row.comm IS NOT NULL OR comm IS NOT NULL AND io_new_row.comm IS NULL) OR
(deptno != io_new_row.deptno OR deptno IS NULL AND io_new_row.deptno IS NOT NULL OR deptno IS NOT NULL AND io_new_row.deptno IS NULL)
);
print_line(
in_proc => 'do_upd',
in_level => co_debug,
in_line => SQL%ROWCOUNT || ' rows updated.'
);
END do_upd;
--
-- do_del
--
PROCEDURE do_del (
in_row IN emp_ot
) IS
BEGIN
DELETE
FROM emp_lt
WHERE empno = in_row.empno;
print_line(
in_proc => 'do_del',
in_level => co_debug,
in_line => SQL%ROWCOUNT || ' rows deleted.'
);
END do_del;
--
-- ins
--
PROCEDURE ins (
in_new_row IN emp_ot
) IS
l_new_row emp_ot;
BEGIN
print_line(in_proc => 'ins', in_level => co_info, in_line => 'started.');
l_new_row := in_new_row;
<<pre_ins>>
BEGIN
emp_hook.pre_ins(io_new_row => l_new_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_ins;
do_ins(io_row => l_new_row);
<<post_ins>>
BEGIN
emp_hook.post_ins(in_new_row => l_new_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END post_ins;
print_line(in_proc => 'ins', in_level => co_info, in_line => 'completed.');
END ins;
--
-- upd
--
PROCEDURE upd (
in_new_row IN emp_ot,
in_old_row IN emp_ot
) IS
l_new_row emp_ot;
BEGIN
print_line(in_proc => 'upd', in_level => co_info, in_line => 'started.');
l_new_row := in_new_row;
<<pre_upd>>
BEGIN
emp_hook.pre_upd(io_new_row => l_new_row, in_old_row => in_new_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_upd;
do_upd(io_new_row => l_new_row, in_old_row => in_old_row);
<<post_upd>>
BEGIN
emp_hook.post_upd(in_new_row => l_new_row, in_old_row => in_old_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END post_upd;
print_line(in_proc => 'upd', in_level => co_info, in_line => 'completed.');
END upd;
--
-- del
--
PROCEDURE del (
in_old_row IN emp_ot
) IS
BEGIN
print_line(in_proc => 'del', in_level => co_info, in_line => 'started.');
<<pre_del>>
BEGIN
emp_hook.pre_del(in_old_row => in_old_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_del;
do_del(in_row => in_old_row);
<<post_del>>
BEGIN
emp_hook.post_del(in_old_row => in_old_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END post_del;
print_line(in_proc => 'del', in_level => co_info, in_line => 'completed.');
END del;
--
-- set_debug_output
--
PROCEDURE set_debug_output (
in_level IN dbms_output_level_type DEFAULT co_off
) IS
BEGIN
g_debug_output_level := in_level;
END set_debug_output;
END emp_api;
/CREATE OR REPLACE PACKAGE BODY emp_api AS
--
-- Note: SQL Developer 4.1.3 cannot produce a complete outline of this package body, because it cannot handle
-- the complete flashback_query_clause. The following expression breaks SQL Developer:
--
-- VERSIONS PERIOD FOR vt$ BETWEEN MINVALUE AND MAXVALUE
--
-- It's expected that future versions will be able to handle the flashback_query_clause accordingly.
-- See "Bug 24608738 - OUTLINE OF PL/SQL PACKAGE BODY BREAKS WHEN USING PERIOD FOR OF FLASHBACK_QUERY_"
-- on MOS for details.
--
--
-- Declarations to handle 'ORA-06508: PL/SQL: could not find program unit being called: "SCOTT.EMP_HOOK"'
--
e_hook_body_missing EXCEPTION;
PRAGMA exception_init(e_hook_body_missing, -6508);
--
-- Debugging output level
--
g_debug_output_level dbms_output_level_type := co_off;
--
-- print_line
--
PROCEDURE print_line (
in_proc IN VARCHAR2,
in_level IN dbms_output_level_type,
in_line IN VARCHAR2
) IS
BEGIN
IF in_level <= g_debug_output_level THEN
sys.dbms_output.put(to_char(systimestamp, 'HH24:MI:SS.FF6'));
CASE in_level
WHEN co_info THEN
sys.dbms_output.put(' INFO ');
WHEN co_debug THEN
sys.dbms_output.put(' DEBUG ');
ELSE
sys.dbms_output.put(' TRACE ');
END CASE;
sys.dbms_output.put(substr(rpad(in_proc,27), 1, 27) || ' ');
sys.dbms_output.put_line(substr(in_line, 1, 250));
END IF;
END print_line;
--
-- print_lines
--
PROCEDURE print_lines (
in_proc IN VARCHAR2,
in_level IN dbms_output_level_type,
in_lines IN CLOB
) IS
BEGIN
IF in_level <= g_debug_output_level THEN
<<all_lines>>
FOR r_line IN (
SELECT regexp_substr(in_lines, '[^' || chr(10) || ']+', 1, level) AS line
FROM dual
CONNECT BY instr(in_lines, chr(10), 1, level - 1) BETWEEN 1 AND length(in_lines) - 1
) LOOP
print_line(in_proc => in_proc, in_level => in_level, in_line => r_line.line);
END LOOP all_lines;
END IF;
END print_lines;
--
-- do_ins
--
PROCEDURE do_ins (
io_row IN OUT emp_ot
) IS
BEGIN
INSERT INTO emp_lt (
empno,
ename,
job,
mgr,
hiredate,
sal,
comm,
deptno
)
VALUES (
io_row.empno,
io_row.ename,
io_row.job,
io_row.mgr,
io_row.hiredate,
io_row.sal,
io_row.comm,
io_row.deptno
)
RETURNING empno
INTO io_row.empno;
print_line(
in_proc => 'do_ins',
in_level => co_debug,
in_line => SQL%ROWCOUNT || ' rows inserted.'
);
END do_ins;
--
-- do_upd
--
PROCEDURE do_upd (
io_new_row IN OUT emp_ot,
in_old_row IN emp_ot
) IS
BEGIN
UPDATE emp_lt
SET empno = io_new_row.empno,
ename = io_new_row.ename,
job = io_new_row.job,
mgr = io_new_row.mgr,
hiredate = io_new_row.hiredate,
sal = io_new_row.sal,
comm = io_new_row.comm,
deptno = io_new_row.deptno
WHERE empno = in_old_row.empno
AND (
(ename != io_new_row.ename OR ename IS NULL AND io_new_row.ename IS NOT NULL OR ename IS NOT NULL AND io_new_row.ename IS NULL) OR
(job != io_new_row.job OR job IS NULL AND io_new_row.job IS NOT NULL OR job IS NOT NULL AND io_new_row.job IS NULL) OR
(mgr != io_new_row.mgr OR mgr IS NULL AND io_new_row.mgr IS NOT NULL OR mgr IS NOT NULL AND io_new_row.mgr IS NULL) OR
(hiredate != io_new_row.hiredate OR hiredate IS NULL AND io_new_row.hiredate IS NOT NULL OR hiredate IS NOT NULL AND io_new_row.hiredate IS NULL) OR
(sal != io_new_row.sal OR sal IS NULL AND io_new_row.sal IS NOT NULL OR sal IS NOT NULL AND io_new_row.sal IS NULL) OR
(comm != io_new_row.comm OR comm IS NULL AND io_new_row.comm IS NOT NULL OR comm IS NOT NULL AND io_new_row.comm IS NULL) OR
(deptno != io_new_row.deptno OR deptno IS NULL AND io_new_row.deptno IS NOT NULL OR deptno IS NOT NULL AND io_new_row.deptno IS NULL)
);
print_line(
in_proc => 'do_upd',
in_level => co_debug,
in_line => SQL%ROWCOUNT || ' rows updated.'
);
END do_upd;
--
-- do_del
--
PROCEDURE do_del (
in_row IN emp_ot
) IS
BEGIN
DELETE
FROM emp_lt
WHERE empno = in_row.empno;
print_line(
in_proc => 'do_del',
in_level => co_debug,
in_line => SQL%ROWCOUNT || ' rows deleted.'
);
END do_del;
--
-- ins
--
PROCEDURE ins (
in_new_row IN emp_ot
) IS
l_new_row emp_ot;
BEGIN
print_line(in_proc => 'ins', in_level => co_info, in_line => 'started.');
l_new_row := in_new_row;
<<pre_ins>>
BEGIN
emp_hook.pre_ins(io_new_row => l_new_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_ins;
do_ins(io_row => l_new_row);
<<post_ins>>
BEGIN
emp_hook.post_ins(in_new_row => l_new_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END post_ins;
print_line(in_proc => 'ins', in_level => co_info, in_line => 'completed.');
END ins;
--
-- upd
--
PROCEDURE upd (
in_new_row IN emp_ot,
in_old_row IN emp_ot
) IS
l_new_row emp_ot;
BEGIN
print_line(in_proc => 'upd', in_level => co_info, in_line => 'started.');
l_new_row := in_new_row;
<<pre_upd>>
BEGIN
emp_hook.pre_upd(io_new_row => l_new_row, in_old_row => in_new_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_upd;
do_upd(io_new_row => l_new_row, in_old_row => in_old_row);
<<post_upd>>
BEGIN
emp_hook.post_upd(in_new_row => l_new_row, in_old_row => in_old_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END post_upd;
print_line(in_proc => 'upd', in_level => co_info, in_line => 'completed.');
END upd;
--
-- del
--
PROCEDURE del (
in_old_row IN emp_ot
) IS
BEGIN
print_line(in_proc => 'del', in_level => co_info, in_line => 'started.');
<<pre_del>>
BEGIN
emp_hook.pre_del(in_old_row => in_old_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_del;
do_del(in_row => in_old_row);
<<post_del>>
BEGIN
emp_hook.post_del(in_old_row => in_old_row);
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END post_del;
print_line(in_proc => 'del', in_level => co_info, in_line => 'completed.');
END del;
--
-- set_debug_output
--
PROCEDURE set_debug_output (
in_level IN dbms_output_level_type DEFAULT co_off
) IS
BEGIN
g_debug_output_level := in_level;
END set_debug_output;
END emp_api;
/Now you may ask what the performance impact of these e_hook_body_missing exceptions are. I’ve done a small test and called a procedure without and with implemented body 1 million times. The overhead of the missing body exception is about 7 microseconds per call. Here’s the test output from SQL Developer, the relevant lines 51 and 89 are highlighted.
SQL> SET FEEDBACK ON
SQL> SET ECHO ON
SQL> SET TIMING ON
SQL> DROP PACKAGE dummy_api;
Package DUMMY_API dropped.
Elapsed: 00:00:00.027
SQL> DROP PACKAGE dummy_hook;
Package DUMMY_HOOK dropped.
Elapsed: 00:00:00.030
SQL> CREATE OR REPLACE PACKAGE dummy_hook AS
PROCEDURE pre_ins;
END dummy_hook;
/
Package DUMMY_HOOK compiled
Elapsed: 00:00:00.023
SQL> CREATE OR REPLACE PACKAGE dummy_api AS
PROCEDURE ins;
END dummy_api;
/
Package DUMMY_API compiled
Elapsed: 00:00:00.034
SQL> CREATE OR REPLACE PACKAGE BODY dummy_api AS
e_hook_body_missing EXCEPTION;
PRAGMA exception_init(e_hook_body_missing, -6508);
PROCEDURE ins IS
BEGIN
BEGIN
dummy_hook.pre_ins;
EXCEPTION
WHEN e_hook_body_missing THEN
NULL;
END pre_ins;
dbms_output.put('.');
END ins;
END dummy_api;
/
Package body DUMMY_API compiled
Elapsed: 00:00:00.040
SQL> -- without hook body
SQL> BEGIN
FOR i IN 1..1E6 LOOP
dummy_api.ins;
END LOOP;
END;
/
PL/SQL procedure successfully completed.
Elapsed: 00:00:07.878
SQL> CREATE OR REPLACE PACKAGE BODY dummy_hook AS
PROCEDURE pre_ins IS
BEGIN
dbms_output.put('-');
END pre_ins;
END dummy_hook;
/
Package body DUMMY_HOOK compiled
Elapsed: 00:00:00.029
SQL> -- with hook body
SQL> BEGIN
FOR i IN 1..1E6 LOOP
dummy_api.ins;
END LOOP;
END;
/
PL/SQL procedure successfully completed.
Elapsed: 00:00:00.632It make sense to provide a body with a NULL implementation to avoid the small overhead of handling the missing body exception.
Nonetheless, the way how the business logic is separated from the generated code, is one of the many things I like about Bitemp Remodeler.
Download Bitemp Remodeler from the Download section on my blog or install it directly via the SQL Developer update site http://update.oddgen.org/