1 PACKAGE fnd_plsql_cache AS
2 /* $Header: AFUTPSCS.pls 120.1.12010000.1 2008/07/25 14:23:35 appldev ship $ */
3
4 -- ----------------------------------------------------------------------
5 -- PL/SQL Caching:
6 --
7 -- Basic caching idea in this package is a VALUE (One-to-One cache) or
8 -- 0 or more VALUEs (One-to-Many cache) are cached for a KEY.
9 --
10 -- KEY's type is VARCHAR2(2000). In your application, if you have
11 -- composite key, you need to concatenate those composite keys and
12 -- pass in as a single varchar2 key. When you concatenate it is better
13 -- if a delimiter is used between keys.
14 -- Example : Consider following two different keys. Without delimiter
15 -- both keys appear to be same when concatenated.
16 -- Concatenated Key
17 -- w/o delimiter w/ delimiter
18 -- -------------- ------------
19 -- Key1 : 'AB', Key2 : 'CD' 'ABCD' 'AB.CD'
20 -- Key1 : 'A', Key2 : 'BCD' 'ABCD' 'A.BCD'
21 --
22 -- VALUE can be the generic value defined in this package, or it can be
23 -- a custom RECORD defined in your package.
24 --
25 -- VALUEs is table of VALUE. It can be generic_values table defined in this
26 -- package, or a custom TABLE of RECORD defined in your package.
27 --
28 -- Type of VALUE:
29 -- Generic Cache: In this cache, the value type is generic_cache_value_type
30 -- which is a RECORD, and has 15 varchar2, 5 number, 3 date, and
31 -- 3 boolean elements.
32 --
33 -- Custom Cache: In this cache, the value type is a custom RECORD defined
34 -- in your package.
35 --
36 -- Number of VALUEs per KEY:
37 -- One-to-One (1to1) Cache: In this cache, there is only one VALUE
38 -- for a KEY.
39 --
40 -- One-to-Many (1toM) Cache: In this cache, there may be 0 or more VALUEs
41 -- for a KEY.
42 --
43 -- Based on number of VALUEs and the type of VALUE, there are four different
44 -- caches provided in this package.
45 --
46 -- Generic Custom
47 -- --------------- ---------------
48 -- 1to1: generic_1to1_* custom_1to1_*
49 -- 1tom: generic_1tom_* custom_1tom_*
50 --
51 -- Usage:
52 -- Please see procedure sample_package() in package body for usage examples.
53 -- The basic usage is
54 -- -- Initialize cache in your package initialization section.
55 -- -- Call GET function to get the VALUE for KEY
56 -- -- If KEY doesn't exist in cache, then get the VALUE from database
57 -- and PUT it in the cache. So that, in the next GET call, VALUE will
58 -- come from cache.
59 --
60
61 -- ----------------------------------------------------------------------
62 -- Return Codes.
63 --
64 CACHE_FOUND CONSTANT VARCHAR2(1) := '1';
65 CACHE_NOTFOUND CONSTANT VARCHAR2(1) := '0';
66 CACHE_VALID CONSTANT VARCHAR2(1) := 'V';
67 CACHE_INVALID CONSTANT VARCHAR2(1) := 'I';
68
69 CACHE_PUT_IS_SUCCESSFUL CONSTANT VARCHAR2(1) := 'P';
70 CACHE_IS_FULL CONSTANT VARCHAR2(1) := 'F';
71 CACHE_TOO_MANY_VALUES_PER_KEY CONSTANT VARCHAR2(1) := 'M';
72
73 -- ----------------------------------------------------------------------
74 -- Cache Debug Levels.
75 --
76 -- Only the cache summary is printed out
77 CDL_SUMMARY CONSTANT VARCHAR2(30) := 'SUMMARY';
78
79 -- Cache summary, and keys are printed out
80 CDL_SUMMARY_KEYS CONSTANT VARCHAR2(30) := 'SUMMARY_KEYS';
81
82 -- Cache summary, keys, and values (Generic) are printed out
83 CDL_SUMMARY_KEYS_VALUES CONSTANT VARCHAR2(30) := 'SUMMARY_KEYS_VALUES';
84
85 -- ----------------------------------------------------------------------
86 -- Cache Types
87 --
88 CACHE_TYPE_GENERIC CONSTANT VARCHAR2(30) := 'GENERIC';
89 CACHE_TYPE_CUSTOM CONSTANT VARCHAR2(30) := 'CUSTOM';
90
91 -- ----------------------------------------------------------------------
92 -- Generic Cache Value. (like Object in Java, or void* in C.)
93 -- This is the value of (Key, Value) pair.
94 -- Used by generic_* functions.'
95 --
96 -- If you need more fields per value, please create a custom value type
97 -- and use custom_* functions.
98 --
99 TYPE generic_cache_value_type IS RECORD
100 (varchar2_1 VARCHAR2(2000), -- 15 varchar2 elements
101 varchar2_2 VARCHAR2(2000),
102 varchar2_3 VARCHAR2(2000),
103 varchar2_4 VARCHAR2(2000),
104 varchar2_5 VARCHAR2(2000),
105 varchar2_6 VARCHAR2(2000),
106 varchar2_7 VARCHAR2(2000),
107 varchar2_8 VARCHAR2(2000),
108 varchar2_9 VARCHAR2(2000),
109 varchar2_10 VARCHAR2(2000),
110 varchar2_11 VARCHAR2(2000),
111 varchar2_12 VARCHAR2(2000),
112 varchar2_13 VARCHAR2(2000),
113 varchar2_14 VARCHAR2(2000),
114 varchar2_15 VARCHAR2(2000),
115 number_1 NUMBER, -- 5 number elements
116 number_2 NUMBER,
117 number_3 NUMBER,
118 number_4 NUMBER,
119 number_5 NUMBER,
120 date_1 DATE, -- 3 date elements
121 date_2 DATE,
122 date_3 DATE,
123 boolean_1 BOOLEAN, -- 3 boolean elements
124 boolean_2 BOOLEAN,
125 boolean_3 BOOLEAN);
126
127 -- ----------------------------------------------------------------------
128 -- Array of generic cache values.
129 -- Used by generic_* functions.
130 --
131 TYPE generic_cache_values_type IS TABLE OF generic_cache_value_type
132 INDEX BY BINARY_INTEGER;
133
134 -- ----------------------------------------------------------------------
135 -- Indexes of custom values.
136 -- Used by custom_* functions.
137 --
138 TYPE custom_cache_indexes_type IS TABLE OF BINARY_INTEGER
139 INDEX BY BINARY_INTEGER;
140
141 -- ----------------------------------------------------------------------
142 -- Limits
143 --
144 -- CACHE_MAX_NUMOF_KEYS :
145 -- Keys are stored in a VARRAY(1024) of VARCHAR2(2048).
146 -- So the maximum number of keys is 1024.
147 --
148 -- CACHE_NUMOF_DIGITS_PER_INDEX :
149 -- Indexes are stored as base-10 numbers in a varchar2 variable.
150 -- Internally indexes are stored as concatenated. Each index occupies 4
151 -- chars of space. Absolute maximum is 9999. The practical max is 8000.
152 -- The concatenated string is stored in a varchar2(32000) variable.
153 -- Here is a sample concatenated indexes:
154 -- Concatenated : '1 2 30 40 500 600 700080009 '
155 -- Indexes : '1,2,30,40,500,600,7000,8000,9'
156 --
157 -- CACHE_MAX_NUMOF_VALUES_PER_KEY :
158 -- Value indexes are stored in a VARRAY(1024) of VARCHAR2(2048).
159 -- So, for a given key we have 2048 bytes of storage for value indexes.
160 -- Each index takes 4 chars space, so we can have up to
161 -- 2048/4=512 values per key.
162 --
163 -- CACHE_MAX_NUMOF_VALUES :
164 -- All available indexes are stored in a varchar2(32000) variable.
165 -- So the maximum number of indexes that can be stored in this variable
166 -- is 32000/4=8000. This is the maximum number of values that can be stored
167 -- in a 1tom cache.
168 --
169 CACHE_MAX_NUMOF_KEYS CONSTANT NUMBER := 1024;
170 CACHE_NUMOF_DIGITS_PER_INDEX CONSTANT NUMBER := 4;
171 CACHE_MAX_NUMOF_VALUES_PER_KEY CONSTANT NUMBER := 512;
172 CACHE_MAX_NUMOF_VALUES CONSTANT NUMBER := 8000;
173
174 -- ----------------------------------------------------------------------
175 -- Auxiliary varrays for cache controller.
176 --
177 TYPE cache_varchar2_varray_type IS VARRAY(1024) OF VARCHAR2(2048);
178 TYPE cache_number_varray_type IS VARRAY(1024) OF NUMBER;
179
180 -- ----------------------------------------------------------------------
181 -- One-to-One Cache Controller :
182 -- Keeps track of information about cache, and keys.
183 -- This cache is a simple one-to-one hash table lookup.
184 --
185 -- Following example shows the caching process.
186 --
187 -- Start-up:
188 -- Init('Country Capitals')
189 -- name : 'Country Capitals'
190 -- max_numof_keys : 1024
191 --
192 -- Put('USA', 'Washington DC') {say hash key is 23}
193 --
194 -- keys(23) : 'USA'
195 -- values(23) : 'Washington DC'
196 --
197 -- Put('Turkey', 'Ankara') {say hash key is 34}
198 --
199 -- keys(34) : 'Turkey'
200 -- values(34) : 'Ankara'
201 --
202 -- Put('France', 'Paris') {say hash key is 23}
203 -- Note that 23 was already in use. New entry will overwrite
204 -- the old entry. i.e. 'USA' entry is dropped from the cache.
205 --
206 -- keys(23) : 'France'
207 -- values(23) : 'Paris'
208 --
209 TYPE cache_1to1_controller_type IS RECORD
210 (name VARCHAR2(30), -- identifier
211 cache_type VARCHAR2(30), -- GENERIC, or CUSTOM
212 max_numof_keys NUMBER, -- max # of keys
213 numof_keys NUMBER, -- # of keys
214 keys cache_varchar2_varray_type); -- keys
215
216 -- ----------------------------------------------------------------------
217 -- One-to-Many Cache Controller :
218 -- Keeps track of information about cache, keys, and corresponding
219 -- indexes in the value array for the values of a key.
220 --
221 -- This cache is designed so that any number of elements can be cached
222 -- for a given key. Basically result set of the SELECT statement is
223 -- cached (and SELECT can return 0, 1, or more rows.)
224 --
225 -- Following example shows the caching process.
226 --
227 -- Start-up:
228 -- Init('Courses for a given student.')
229 -- name : 'Courses for a given student.'
230 -- max_numof_keys : 1024
231 -- available_indexes : '1,2,3,4,5,6,7,8,9,10,...'
232 --
233 -- Put('Bill Gates', ['Math', 'C Prog', 'Chem']) {say hash key is 23}
234 --
235 -- keys(23) : 'Bill Gates'
236 -- numof_indexes(23) : 3
237 -- value_indexes(23) : '1,2,3,'
238 -- available_indexes : '4,5,6,7,8,9,10,...'
239 --
240 -- values(1) : 'Math'
241 -- values(2) : 'C Prog'
242 -- values(3) : 'Chem'
243 --
244 -- Put('Bill Clinton', ['Law', 'History','Economy']) {say hash key is 34}
245 --
246 -- keys(34) : 'Bill Clinton'
247 -- numof_indexes(34) : 3
248 -- value_indexes(34) : '4,5,6,'
249 -- available_indexes : '7,8,9,10,...'
250 --
251 -- values(4) : 'Law'
252 -- values(5) : 'History'
253 -- values(6) : 'Economy'
254 --
255 -- Put('Larry Ellison', ['Science']) {say hash key is 23}
256 -- Note that 23 was already in use. New entry will overwrite the
257 -- old entry. Old entry's indexes are returned to available list.
258 -- i.e. 'Bill Gates' entry is dropped from the cache.
259 --
260 -- keys(23) : 'Larry Ellison'
261 -- numof_indexes(23) : 1
262 -- value_indexes(23) : '1,'
263 -- available_indexes : '2,3,7,8,9,10,...'
264 --
265 -- values(1) : 'Science'
266 --
267 TYPE cache_1tom_controller_type IS RECORD
268 (name VARCHAR2(30), -- identifier
269 cache_type VARCHAR2(30), -- GENERIC, or CUSTOM
270 max_numof_keys NUMBER, -- max # of keys
271 numof_keys NUMBER, -- # of keys
272 keys cache_varchar2_varray_type, -- keys
273 numof_values NUMBER, -- # of values
274
275 numof_indexes cache_number_varray_type, -- # of values per key
276 value_indexes cache_varchar2_varray_type, -- value indexes
277 numof_available_indexes NUMBER, -- remaining # of idxs
278 maxof_available_indexes NUMBER, -- max of indexes
279 available_indexes VARCHAR2(32000)); -- free indexes.
280
281 -- ----------------------------------------------------------------------
282 -- New generic cache value.
283 -- ----------------------------------------------------------------------
284 PROCEDURE generic_cache_new_value
285 (x_value OUT nocopy generic_cache_value_type,
286 p_varchar2_1 IN VARCHAR2 DEFAULT NULL,
287 p_varchar2_2 IN VARCHAR2 DEFAULT NULL,
288 p_varchar2_3 IN VARCHAR2 DEFAULT NULL,
289 p_varchar2_4 IN VARCHAR2 DEFAULT NULL,
290 p_varchar2_5 IN VARCHAR2 DEFAULT NULL,
291 p_varchar2_6 IN VARCHAR2 DEFAULT NULL,
292 p_varchar2_7 IN VARCHAR2 DEFAULT NULL,
293 p_varchar2_8 IN VARCHAR2 DEFAULT NULL,
294 p_varchar2_9 IN VARCHAR2 DEFAULT NULL,
295 p_varchar2_10 IN VARCHAR2 DEFAULT NULL,
296 p_varchar2_11 IN VARCHAR2 DEFAULT NULL,
297 p_varchar2_12 IN VARCHAR2 DEFAULT NULL,
298 p_varchar2_13 IN VARCHAR2 DEFAULT NULL,
299 p_varchar2_14 IN VARCHAR2 DEFAULT NULL,
300 p_varchar2_15 IN VARCHAR2 DEFAULT NULL,
301 p_number_1 IN NUMBER DEFAULT NULL,
302 p_number_2 IN NUMBER DEFAULT NULL,
303 p_number_3 IN NUMBER DEFAULT NULL,
304 p_number_4 IN NUMBER DEFAULT NULL,
305 p_number_5 IN NUMBER DEFAULT NULL,
306 p_date_1 IN DATE DEFAULT NULL,
307 p_date_2 IN DATE DEFAULT NULL,
308 p_date_3 IN DATE DEFAULT NULL,
309 p_boolean_1 IN BOOLEAN DEFAULT NULL,
310 p_boolean_2 IN BOOLEAN DEFAULT NULL,
311 p_boolean_3 IN BOOLEAN DEFAULT NULL);
312
313 FUNCTION generic_cache_new_value
314 (p_varchar2_1 IN VARCHAR2 DEFAULT NULL,
315 p_varchar2_2 IN VARCHAR2 DEFAULT NULL,
316 p_varchar2_3 IN VARCHAR2 DEFAULT NULL,
317 p_varchar2_4 IN VARCHAR2 DEFAULT NULL,
318 p_varchar2_5 IN VARCHAR2 DEFAULT NULL,
319 p_varchar2_6 IN VARCHAR2 DEFAULT NULL,
320 p_varchar2_7 IN VARCHAR2 DEFAULT NULL,
321 p_varchar2_8 IN VARCHAR2 DEFAULT NULL,
322 p_varchar2_9 IN VARCHAR2 DEFAULT NULL,
323 p_varchar2_10 IN VARCHAR2 DEFAULT NULL,
324 p_varchar2_11 IN VARCHAR2 DEFAULT NULL,
325 p_varchar2_12 IN VARCHAR2 DEFAULT NULL,
326 p_varchar2_13 IN VARCHAR2 DEFAULT NULL,
327 p_varchar2_14 IN VARCHAR2 DEFAULT NULL,
328 p_varchar2_15 IN VARCHAR2 DEFAULT NULL,
329 p_number_1 IN NUMBER DEFAULT NULL,
330 p_number_2 IN NUMBER DEFAULT NULL,
331 p_number_3 IN NUMBER DEFAULT NULL,
332 p_number_4 IN NUMBER DEFAULT NULL,
333 p_number_5 IN NUMBER DEFAULT NULL,
334 p_date_1 IN DATE DEFAULT NULL,
335 p_date_2 IN DATE DEFAULT NULL,
336 p_date_3 IN DATE DEFAULT NULL,
337 p_boolean_1 IN BOOLEAN DEFAULT NULL,
338 p_boolean_2 IN BOOLEAN DEFAULT NULL,
339 p_boolean_3 IN BOOLEAN DEFAULT NULL)
340 RETURN generic_cache_value_type;
341
342
343 -- ======================================================================
344 -- Generic 1to1 Cache:
345 -- One Value per Key. Value type is generic_cache_value_type.
346 --
347 -- In generic 1to1 cache, key is stored in the controller, and the
348 -- value is stored in the value storage array.
349 -- ======================================================================
350 -- ----------------------------------------------------------------------
351 -- Initialize the generic_1to1 cache.
352 --
353 -- This procedure should be called in package initialization section.
354 --
355 -- @param p_name - Name of the cache
356 -- @param px_controller - 1to1 controller for this cache
357 -- @param px_storage - Storage array for the values
358 -- @param p_max_numof_keys - Maximum number of keys. Must be power of 2.
359 -- 1 <= p_max_numof_keys <= CACHE_MAX_NUMOF_KEYS
360 --
361 -- For usage example, please see sample_package() procedure in the body.
362 -- ----------------------------------------------------------------------
363 PROCEDURE generic_1to1_init
364 (p_name IN VARCHAR2,
365 px_controller IN OUT nocopy cache_1to1_controller_type,
369 -- ----------------------------------------------------------------------
366 px_storage IN OUT nocopy generic_cache_values_type,
367 p_max_numof_keys IN NUMBER DEFAULT CACHE_MAX_NUMOF_KEYS);
368
370 -- Get value
371 --
372 -- For a given key, this procedure returns the value.
373 --
374 -- @param px_controller - 1to1 controller for this cache
375 -- @param px_storage - Storage array for the values
376 -- @param p_key - Key
377 -- @param x_value - Value
378 -- @param x_return_code - Return code. See CACHE_* constants above.
379 --
380 -- For usage example, please see sample_package() procedure in the body.
381 -- ----------------------------------------------------------------------
382 PROCEDURE generic_1to1_get_value
383 (px_controller IN OUT nocopy cache_1to1_controller_type,
384 px_storage IN OUT nocopy generic_cache_values_type,
385 p_key IN VARCHAR2,
386 x_value OUT nocopy generic_cache_value_type,
387 x_return_code OUT nocopy VARCHAR2);
388
389 -- ----------------------------------------------------------------------
390 -- Put value
391 --
392 -- For a given key, this procedure puts the value in cache.
393 --
394 -- @param px_controller - 1to1 controller for this cache
395 -- @param px_storage - Storage array for the values
396 -- @param p_key - Key
397 -- @param p_value - Value
398 --
399 -- For usage example, please see sample_package() procedure in the body.
400 -- ----------------------------------------------------------------------
401 PROCEDURE generic_1to1_put_value
402 (px_controller IN OUT nocopy cache_1to1_controller_type,
403 px_storage IN OUT nocopy generic_cache_values_type,
404 p_key IN VARCHAR2,
405 p_value IN generic_cache_value_type);
406
407 -- ----------------------------------------------------------------------
408 -- Remove key
409 --
410 -- For a given key, this procedure removes the key from the cache.
411 --
412 -- @param px_controller - 1to1 controller for this cache
413 -- @param p_key - Key
414 -- ----------------------------------------------------------------------
415 PROCEDURE generic_1to1_remove_key
416 (px_controller IN OUT nocopy cache_1to1_controller_type,
417 p_key IN VARCHAR2);
418
419 -- ----------------------------------------------------------------------
420 -- Clears the cache.
421 --
422 -- @param px_controller - 1to1 controller for this cache
423 -- @param px_storage - Storage array for the values
424 -- ----------------------------------------------------------------------
425 PROCEDURE generic_1to1_clear
426 (px_controller IN OUT nocopy cache_1to1_controller_type,
427 px_storage IN OUT nocopy generic_cache_values_type);
428
429 -- ----------------------------------------------------------------------
430 -- Debugs the cache.
431 --
432 -- @param px_controller - 1to1 controller for this cache
433 -- @param px_storage - Storage array for the values
434 -- @param p_debug_level - Debug level, see CDL_* constants above
435 -- ----------------------------------------------------------------------
436 PROCEDURE generic_1to1_debug
437 (px_controller IN cache_1to1_controller_type,
438 px_storage IN generic_cache_values_type,
439 p_debug_level IN VARCHAR2 DEFAULT CDL_SUMMARY_KEYS_VALUES);
440
441
442 -- ======================================================================
443 -- Generic 1toM Cache:
444 -- Many Values per Key. Value type is generic_cache_value_type.
445 --
446 -- In generic 1toM cache, key is stored in the controller, and the
447 -- values are stored in the value storage array.
448 -- ======================================================================
449 -- ----------------------------------------------------------------------
450 -- Initialize the generic_1tom cace.
451 --
452 -- This procedure should be called in package initialization section.
453 --
454 -- @param p_name - Name of the cache
455 -- @param px_controller - 1tom controller for this cache
456 -- @param px_storage - Storage array for the values
457 -- @param p_max_numof_keys - Maximum number of keys. Must be power of 2.
458 -- 1 <= p_max_numof_keys <= CACHE_MAX_NUMOF_KEYS
459 --
460 -- For usage example, please see sample_package() procedure in the body.
461 -- ----------------------------------------------------------------------
462 PROCEDURE generic_1tom_init
463 (p_name IN VARCHAR2,
464 px_controller IN OUT nocopy cache_1tom_controller_type,
465 px_storage IN OUT nocopy generic_cache_values_type,
466 p_max_numof_keys IN NUMBER DEFAULT CACHE_MAX_NUMOF_KEYS);
467
468 -- ----------------------------------------------------------------------
469 -- Get values
470 --
471 -- For a given key, this procedure returns the values.
472 --
473 -- @param px_controller - 1tom controller for this cache
474 -- @param px_storage - Storage array for the values
475 -- @param p_key - Key
476 -- @param x_numof_values - Number of values
477 -- 0 <= x_numof_values <= CACHE_MAX_NUMOF_VALUES_PER_KEY
478 -- @param x_values - Values
479 -- @param x_return_code - Return code. See CACHE_* constants above.
480 --
481 -- For usage example, please see sample_package() procedure in the body.
482 -- ----------------------------------------------------------------------
483 PROCEDURE generic_1tom_get_values
487 x_numof_values OUT nocopy NUMBER,
484 (px_controller IN OUT nocopy cache_1tom_controller_type,
485 px_storage IN OUT nocopy generic_cache_values_type,
486 p_key IN VARCHAR2,
488 x_values OUT nocopy generic_cache_values_type,
489 x_return_code OUT nocopy VARCHAR2);
490
491 -- ----------------------------------------------------------------------
492 -- Put values
493 --
494 -- For a given key, this procedure puts the values in cache.
495 --
496 -- @param px_controller - 1tom controller for this cache
497 -- @param px_storage - Storage array for the values
498 -- @param p_key - Key
499 -- @param p_numof_values - Number of values
500 -- 0 <= p_numof_values <= CACHE_MAX_NUMOF_VALUES_PER_KEY
501 -- @param p_values - Values
502 --
503 -- For usage example, please see sample_package() procedure in the body.
504 -- ----------------------------------------------------------------------
505 PROCEDURE generic_1tom_put_values
506 (px_controller IN OUT nocopy cache_1tom_controller_type,
507 px_storage IN OUT nocopy generic_cache_values_type,
508 p_key IN VARCHAR2,
509 p_numof_values IN NUMBER,
510 p_values IN generic_cache_values_type);
511
512 -- ----------------------------------------------------------------------
513 -- Remove key
514 --
515 -- For a given key, this function removes the key from the cache.
516 --
517 -- @param px_controller - 1tom controller for this cache
518 -- @param p_key - Key
519 -- ----------------------------------------------------------------------
520 PROCEDURE generic_1tom_remove_key
521 (px_controller IN OUT nocopy cache_1tom_controller_type,
522 p_key IN VARCHAR2);
523
524 -- ----------------------------------------------------------------------
525 -- Clears the cache.
526 --
527 -- @param px_controller - 1tom controller for this cache
528 -- @param px_storage - Storage array for the values
529 -- ----------------------------------------------------------------------
530 PROCEDURE generic_1tom_clear
531 (px_controller IN OUT nocopy cache_1tom_controller_type,
532 px_storage IN OUT nocopy generic_cache_values_type);
533
534 -- ----------------------------------------------------------------------
535 -- Debugs the cache.
536 --
537 -- @param px_controller - 1tom controller for this cache
538 -- @param px_storage - Storage array for the values
539 -- @param p_debug_level - Debug level, see CDL_* constants above
540 -- ----------------------------------------------------------------------
541 PROCEDURE generic_1tom_debug
542 (px_controller IN cache_1tom_controller_type,
543 px_storage IN generic_cache_values_type,
544 p_debug_level IN VARCHAR2 DEFAULT CDL_SUMMARY_KEYS_VALUES);
545
546
547 -- ======================================================================
548 -- Custom One Cache:
549 -- One Value per Key. Value type is custom.
550 --
551 -- In custom_1to1 cache, key is stored in the controller,
552 -- and value is stored in a custom TABLE OF _RECORD_.
553 -- ======================================================================
554 -- ----------------------------------------------------------------------
555 -- Initialize the custom_1to1 cache.
556 --
557 -- This procedure should be called in package initialization section.
558 --
559 -- @param p_name - Name of the cache
560 -- @param px_controller - 1to1 controller for this cache
561 -- @param p_max_numof_keys - Maximum number of keys. Must be power of 2.
562 -- 1 <= p_max_numof_keys <= CACHE_MAX_NUMOF_KEYS
563 --
564 -- For usage example, please see sample_package() procedure in the body.
565 -- ----------------------------------------------------------------------
566 PROCEDURE custom_1to1_init
567 (p_name IN VARCHAR2,
568 px_controller IN OUT nocopy cache_1to1_controller_type,
569 p_max_numof_keys IN NUMBER DEFAULT CACHE_MAX_NUMOF_KEYS);
570
571 -- ----------------------------------------------------------------------
572 -- Getter for index used in get operation.
573 --
574 -- For a given key, this procedure returns the index to the VALUE. Then
575 -- the actual value should be get using this index.
576 --
577 -- @param px_controller - 1to1 controller for this cache
578 -- @param p_key - Key
579 -- @param x_index - Index to the value
580 -- @param x_return_code - Return code. See CACHE_* constants above.
581 --
582 -- For usage example, please see sample_package() procedure in the body.
583 -- ----------------------------------------------------------------------
584 PROCEDURE custom_1to1_get_get_index
585 (px_controller IN OUT nocopy cache_1to1_controller_type,
586 p_key IN VARCHAR2,
587 x_index OUT nocopy BINARY_INTEGER,
588 x_return_code OUT nocopy VARCHAR2);
589
590 -- ----------------------------------------------------------------------
591 -- Getter for index used in put operations.
592 --
593 -- For a given key, this procedure returns the index to the VALUE. Then
594 -- the actual value should be put using this index.
595 --
596 -- @param px_controller - 1to1 controller for this cache
597 -- @param p_key - Key
598 -- @param x_index - Index to the value
599 --
600 -- For usage example, please see sample_package() procedure in the body.
604 p_key IN VARCHAR2,
601 -- ----------------------------------------------------------------------
602 PROCEDURE custom_1to1_get_put_index
603 (px_controller IN OUT nocopy cache_1to1_controller_type,
605 x_index OUT nocopy BINARY_INTEGER);
606
607 -- ----------------------------------------------------------------------
608 -- Remove key
609 --
610 -- For a given key, this procedure removes the key from the cache.
611 --
612 -- @param px_controller - 1to1 controller for this cache
613 -- @param p_key - Key
614 -- ----------------------------------------------------------------------
615 PROCEDURE custom_1to1_remove_key
616 (px_controller IN OUT nocopy cache_1to1_controller_type,
617 p_key IN VARCHAR2);
618
619 -- ----------------------------------------------------------------------
620 -- Clears the cache.
621 --
622 -- @param px_controller - 1to1 controller for this cache
623 -- ----------------------------------------------------------------------
624 PROCEDURE custom_1to1_clear
625 (px_controller IN OUT nocopy cache_1to1_controller_type);
626
627 -- ----------------------------------------------------------------------
628 -- Debugs the cache.
629 --
630 -- @param px_controller - 1to1 controller for this cache
631 -- @param p_debug_level - Debug level, see CDL_* constants above
632 -- ----------------------------------------------------------------------
633 PROCEDURE custom_1to1_debug
634 (px_controller IN cache_1to1_controller_type,
635 p_debug_level IN VARCHAR2 DEFAULT CDL_SUMMARY_KEYS_VALUES);
636
637
638 -- ======================================================================
639 -- Custom 1toM Cache:
640 -- Many Values per Key. Value type is custom.
641 --
642 -- In custom_1tom cache, key is stored in the controller,
643 -- and values are stored in a custom TABLE OF _RECORD_.
644 -- ======================================================================
645 -- ----------------------------------------------------------------------
646 -- Initialize the custom 1toM cache.
647 --
648 -- This procedure should be called in package initialization section.
649 --
650 -- @param p_name - Name of the cache
651 -- @param px_controller - 1tom controller for this cache
652 -- @param p_max_numof_keys - Maximum number of keys. Must be power of 2.
653 -- 1 <= p_max_numof_keys <= CACHE_MAX_NUMOF_KEYS
654 --
655 -- For usage example, please see sample_package() procedure in the body.
656 -- ----------------------------------------------------------------------
657 PROCEDURE custom_1tom_init
658 (p_name IN VARCHAR2,
659 px_controller IN OUT nocopy cache_1tom_controller_type,
660 p_max_numof_keys IN NUMBER DEFAULT CACHE_MAX_NUMOF_KEYS);
661
662 -- ----------------------------------------------------------------------
663 -- Getter for indexes used in get operations.
664 --
665 -- For a given key, this procedure returns how many values are cached
666 -- {x_numof_indexes} and indexes {x_indexes} to those values in the
667 -- cache table. Then these values should be get using the indexes.
668 --
669 -- @param px_controller - 1tom controller for this cache
670 -- @param p_key - Key
671 -- @param x_numof_indexes - Number of indexes
672 -- 0 <= x_numof_indexes <= CACHE_MAX_NUMOF_VALUES_PER_KEY
673 -- @param x_indexes - Indexes to the values
674 -- @param x_return_code - Return code. See CACHE_* constants above.
675 --
676 -- For usage example, please see sample_package() procedure in the body.
677 -- ----------------------------------------------------------------------
678 PROCEDURE custom_1tom_get_get_indexes
679 (px_controller IN OUT nocopy cache_1tom_controller_type,
680 p_key IN VARCHAR2,
681 x_numof_indexes OUT nocopy NUMBER,
682 x_indexes OUT nocopy custom_cache_indexes_type,
683 x_return_code OUT nocopy VARCHAR2);
684
685 -- ----------------------------------------------------------------------
686 -- Getter for indexes used in put operations.
687 --
688 -- For a given key, this function takes how many values will be cached
689 -- {p_numof_indexes} and returns the indexes {x_indexes} that these values
690 -- should be put in the cache table. Then the actual values should be put
691 -- using these indexes.
692 --
693 -- @param px_controller - 1tom controller for this cache
694 -- @param p_key - Key
695 -- @param p_numof_indexes - Number of indexes
696 -- 0 <= p_numof_indexes <= CACHE_MAX_NUMOF_VALUES_PER_KEY
697 -- @param x_indexes - Indexes to the values
698 -- @param x_return_code - Return code. See CACHE_* constants above.
699 --
700 -- For usage example, please see sample_package() procedure in the body.
701 -- ----------------------------------------------------------------------
702 PROCEDURE custom_1tom_get_put_indexes
703 (px_controller IN OUT nocopy cache_1tom_controller_type,
704 p_key IN VARCHAR2,
705 p_numof_indexes IN NUMBER,
706 x_indexes OUT nocopy custom_cache_indexes_type,
707 x_return_code OUT nocopy VARCHAR2);
708
709 -- ----------------------------------------------------------------------
710 -- Remove key
711 --
712 -- For a given key, this function removes the key from the cache.
713 --
714 -- @param px_controller - 1tom controller for this cache
715 -- @param p_key - Key
716 -- ----------------------------------------------------------------------
717 PROCEDURE custom_1tom_remove_key
718 (px_controller IN OUT nocopy cache_1tom_controller_type,
719 p_key IN VARCHAR2);
720
721 -- ----------------------------------------------------------------------
722 -- Clears the cache.
723 --
724 -- @param px_controller - 1tom controller for this cache
725 -- ----------------------------------------------------------------------
726 PROCEDURE custom_1tom_clear
727 (px_controller IN OUT nocopy cache_1tom_controller_type);
728
729 -- ----------------------------------------------------------------------
730 -- Debugs the cache.
731 --
732 -- @param px_controller - 1tom controller for this cache
733 -- @param p_debug_level - Debug level, see CDL_* constants above
734 -- ----------------------------------------------------------------------
735 PROCEDURE custom_1tom_debug
736 (px_controller IN cache_1tom_controller_type,
737 p_debug_level IN VARCHAR2 DEFAULT CDL_SUMMARY_KEYS_VALUES);
738
739
740 -- ----------------------------------------------------------------------
741 -- Test the cache
742 -- ----------------------------------------------------------------------
743 PROCEDURE test;
744
745 END fnd_plsql_cache;