내용 목차
본 장에서는 DBMS_AQ 패키지의 기본 개념과 패키지 내의 프러시저와 함수를 사용하는 방법을 설명한다.
DBMS_AQ 패키지는 Tibero의 Advanced Queuing 기능과 관련한 프러시저와 함수를 제공한다. Tibero의 Advanced Queuing은 Tibero 데이터베이스와 통합되어 있는 메시지 Queuing 기능이다. 메시지는 데이터베이스 테이블에 영속적으로 저장되며, 필요에 따라 SQL을 통해 직접 queue 테이블의 내용을 조회하는 것도 가능하다.
queue는 단일 소비자 queue 또는 복수 소비자 queue일 수 있다. 단일 소비자 queue에 메시지를 enqueue하면 이 메시지는 오직 하나의 소비자만 dequeue할 수 있으며, 이 dequeue된 메시지를 또 다른 소비자가 dequeue하는 것은 불가능하다. 복수 소비자 queue일 경우는 디폴트 구독자들 또는 별도로 지정한 수신자들을 대상으로 enqueue를 수행할 수 있으며, 이때 각 소비자는 자신을 대상으로 enqueue된 메시지를 dequeue할 수 있다.
tbCLI 클라이언트는 자신이 관심있어 하는 queue에 enqueue가 수행될 때 그 이벤트를 알림으로 받을 수 있도록 자신을 등록할 수 있다. 이때 콜백함수를 명시해 놓으면 알림을 받을 때마다 해당 콜백함수를 수행하는 것이 가능하다.
메시지의 payload 타입은 현재 RAW 타입만 가능하고, tbCLI에서 알림 등록 및 콜백함수 수행에 대해서는 "Tibero tbCLI 안내서"를 참고한다.
IMMEDIATE CONSTANT PLS_INTEGER := 0; ON_COMMIT CONSTANT PLS_INTEGER := 1; BROWSE CONSTANT BINARY_INTEGER := 1; LOCKED CONSTANT BINARY_INTEGER := 2; REMOVE CONSTANT BINARY_INTEGER := 3; REMOVE_NODATA CONSTANT BINARY_INTEGER := 4; FIRST_MESSAGE CONSTANT BINARY_INTEGER := 1; NEXT_MESSAGE CONSTANT BINARY_INTEGER := 3; FOREVER CONSTANT BINARY_INTEGER := -1; NO_WAIT CONSTANT BINARY_INTEGER := 0; NAMESPACE_AQ CONSTANT BINARY_INTEGER := 1;
본 절에서는 DBMS_AQ 패키지에서 제공하는 별도 정의된 타입들을 알파벳 순으로 설명한다.
메시지의 생산자 또는 소비자를 명시할 때 사용하는 타입이다.
프로토타입
TYPE AQ$_AGENT IS RECORD
(
name VARCHAR2(30),
address VARCHAR2(1024) DEFAULT NULL,
protocol NUMBER DEFAULT 0
);
필드
| 필드 이름 | 설명 |
|---|---|
| name | 생산자 또는 소비자의 이름을 명시한다. 객체의 이름을 부여할 때와 동일한 규칙이 적용된다. |
| address | 현재 버전에서는 사용되지 않는다. |
| protocol | 현재 버전에서는 사용되지 않는다. |
메시지를 수신할 agent의 목록을 명시한다. 복수 소비자 queue에 대해서만 이 타입을 사용할 수 있다.
AQ$_RECIPIENT_LIST_T 타입의 세부 내용은 다음과 같다.
프로토타입
TYPE AQ$_RECIPIENT_LIST_T IS TABLE OF AQ$_AGENT
INDEX BY BINARY_INTEGER;
dequeue할 때 적용할 수 있는 옵션들을 명시하는 타입이다.
DEQUEUE_OPTIONS_T 타입의 세부 내용은 다음과 같다.
프로토타입
TYPE DEQUEUE_OPTIONS_T IS RECORD
(
consumer_name VARCHAR2(30) DEFAULT NULL,
dequeue_mode BINARY_INTEGER DEFAULT REMOVE,
navigation BINARY_INTEGER DEFAULT NEXT_MESSAGE,
visibility BINARY_INTEGER DEFAULT ON_COMMIT,
wait BINARY_INTEGER DEFAULT FOREVER,
msgid RAW(16) DEFAULT NULL,
correlation VARCHAR2(128) DEFAULT NULL,
deq_condition VARCHAR2(4000) DEFAULT NULL
);
필드
| 필드 이름 | 설명 |
|---|---|
| consumer_name | 소비자의 이름이다. 이 소비자에게 보내진 메시지만 dequeue가 된다. 단일 소비자 queue에 대해서는 이 값이 NULL이어야 한다. |
| dequeue_mode | dequeue를 수행할 때 수행되는 잠금 방식을 결정한다. 설정 가능한 값은 다음과 같다.
|
| navigation | 가져올 메시지의 위치를 결정한다. 설정 가능한 값은 다음과 같다.
|
| visibility | 메시지를 dequeue하는 동작을 현재 트랜잭션에 같이 포함시킬지 결정한다. dequeue_mode가 BROWSE일 경우 이 값은 무시된다. 설정 가능한 값은 다음과 같다.
|
| wait | 검색 조건에 해당하는 메시지가 없을 때 기다릴 시간을 명시한다. 설정 가능한 값은 다음과 같다.
|
| msgid | dequeue할 메시지 식별자를 명시한다. |
| correlation | dequeue할 메시지의 연관 식별자를 명시한다. 퍼센트 기호(%) 또는 언더바(_)와 같은 패턴 대조에 사용되는 문자를 넣을 수 있다. |
| deq_condition | 메시지 속성 또는 메시지 데이터 속성에 대한 조건식을 지정한다. 이것은 SQL 문의 WHERE 절에 오는 것과 같은 형식의 참/거짓을 가지는 표현식이다. 메시지 속성은 queue 테이블에 존재하는 priority, corrid 또는 기타 다른 컬럼을 포함한다. |
enqueue할 때 취할 수 있는 옵션들을 명시하는 타입이다.
ENQUEUE_OPTIONS_T 타입의 세부 내용은 다음과 같다.
프로토타입
TYPE ENQUEUE_OPTIONS_T IS RECORD
(
visibility BINARY_INTEGER DEFAULT ON_COMMIT
);
필드
| 필드 이름 | 설명 |
|---|---|
| visibility | 메시지를 enqueue하는 동작을 현재 트랜잭션에 같이 포함시킬지 결정한다. 설정 가능한 값은 다음과 같다.
|
메시지 각각에 대한 여러 속성을 명시하는데 사용하는 타입이다. enqueue할 때는 이 속성을 채워서 enqueue하며, dequeue할 때는 채웠던 속성이 반환된다.
MESSAGE_PROPERTIES_T 타입의 세부 내용은 다음과 같다.
프로토타입
TYPE MESSAGE_PROPERTIES_T IS RECORD
(
priority BINARY_INTEGER NOT NULL DEFAULT 1,
correlation VARCHAR2(128) DEFAULT NULL,
recipient_list AQ$_RECIPIENT_LIST_T,
enqueue_time DATE
);
필드
| 필드 이름 | 설명 |
|---|---|
| priority | 메시지의 우선 순위를 명시한다. 숫자가 작을수록 우선 순위가 높은 것이다. 음수를 포함해 어떤 숫자도 가능하다. |
| correlation | 메시지를 enqueue할 때 생산자가 명시할 수 있는 연관 식별자이다. |
| recipient_list | 메시지를 전달할 수신자를 직접 명시할 때 사용하는 AQ$_AGENT agent에 대한 인덱스 테이블이다. 복수 소비자 queue에 대해서만 이 값을 명시할 수 있고, 이 값을 명시하지 않으면 디폴트 구독자들이 수신자가 된다. 이 파라미터는 dequeue할 때 소비자에게 반환되지 않는다. |
| enqueue_time | 메시지가 enqueue된 시점을 반환한다. 이 값은 시스템이 결정하며 enqueue할 때 사용자가 명시할 수 없다. |
이 타입은 dbms_aq.enqueue_array나 dbms_aq.dequeue_array를 호출할 때 여러 메시지에 대한 속성을 함께 명시하기 위해 사용한다. 즉, payload_array에 명시된 payload 갯수만큼 message_properties_array_t varray에 속성들이 명시되어야 한다.
MESSAGE_PROPERTIES_ARRAY_T 타입의 세부 내용은 다음과 같다.
프로토타입
TYPE MESSAGE_PROPERTIES_ARRAY_T IS VARRAY (2147483647)
OF MESSAGE_PROPERTIES_T;
본 절에서는 DBMS_AQ 패키지에서 제공하는 프러시저와 함수를 알파벳 순으로 설명한다.
대상 queue로부터 메시지를 하나 dequeue한다. 어떤 메시지를 dequeue할 것인가는 dequeue_options의 consumer_name, msgid, correlation 또는 deq_condition에 무엇을 명시했느냐에 따라 결정된다. 각각에 대한 설명은 “5.2.3. DEQUEUE_OPTIONS_T”를 참고한다.
dequeue되는 메시지의 순서는 queue 테이블을 생성할 때 명시하는 정렬 순서에 의해 결정된다. dequeue_options에 msgid 또는 correlation을 명시하면 이 순서를 무시할 수 있다. enqueue 및 dequeue도 일반 데이터베이스 동작과 마찬가지로 일관성 읽기 규칙이 적용된다. 예를 들어 BROWSE가 시작되고 나서 enqueue된 메시지가 보이지 않을 수 있다.
navigation 파라미터의 기본값은 NEXT_MESSAGE이다. 이것은 반복적인 dequeue를 수행할 때 맨 처음 dequeue를 수행했을 때의 스냅샷을 기준으로 메시지들이 순차적으로 반환됨을 의미한다. 즉, 첫 번째 dequeue를 수행한 이후에 enqueue된 메시지는 현재 dequeue하고 있는 메시지들이 다 소비된 이후에만 소비가 가능하다. 일반적으로는 이렇게 동작해도 문제가 없지만 우선 순위와 같은 이유로 dequeue할 때 항상 queue의 첫 번째 메시지를 dequeue해야 할 경우는 FIRST_MESSAGE 옵션을 사용해야만 한다. 예를 들어 기존에 enqueue된 메시지를 처리하는 중에 더 높은 우선 순위의 메시지가 enqueue되었을 경우 이를 먼저 처리하기 위해서 이 옵션이 필요하다.
프로토타입
DBMS_AQ.DEQUEUE
(
queue_name IN VARCHAR2,
dequeue_options IN DEQUEUE_OPTIONS_T,
message_properties OUT MESSAGE_PROPERTIES_T,
payload OUT RAW,
msgid OUT RAW
);
파라미터
| 파라미터 | 설명 |
|---|---|
| queue_name | 메시지를 dequeue할 queue의 이름을 명시한다. |
| dequeue_options | dequeue할 모든 메시지에 동일하게 적용되는 옵션을 명시한다. 자세한 내용은 “5.2.3. DEQUEUE_OPTIONS_T”를 참고한다. |
| message_properties | 반환되는 메시지 속성들을 명시한다. 자세한 내용은 “5.2.5. MESSAGE_PROPERTIES_T”를 참고한다. |
| payload | 사용자가 지정하는 payload이다. 현재는 RAW 타입만 가능하다. |
| msgid | dequeue된 메시지에 대한 식별자이다. |
예제
DECLARE
dequeue_options DBMS_AQ.dequeue_options_t;
message_properties DBMS_AQ.message_properties_t;
message_handle RAW(16);
message raw(1000);
BEGIN
dequeue_options.consumer_name := 'RED';
dequeue_options.deq_condition := 'enq_time is not null';
DBMS_AQ.DEQUEUE(
queue_name => 'my_multi_q',
dequeue_options => dequeue_options,
message_properties => message_properties,
payload => message,
msgid => message_handle);
dbms_output.put_line('msgid: ' || message_handle);
END;
/
여러 메시지를 한꺼번에 dequeue하고 그것을 payload의 배열, 메시지 속성의 배열, 메시지 식별자의 배열로 반환하는 함수이다. 함수의 반환값은 성공적으로 dequeue된 메시지의 갯수이다.
dequeue_options에 명시된 wait 시간은 dequeue를 수행할 때 queue에 dequeue할 메시지가 아무것도 존재하지 않을 때만 적용된다. 만일 dequeue할 수 있는 메시지가 queue에 하나 이상 존재하면 DEQUEUE_ARRAY 함수는 최대 array_size 만큼의 메시지를 dequeue한 후 즉시 리턴된다.
dequeue_options로 msgid는 명시할 수 없다. navigation 파라미터와 관련한 내용은 “5.2.3. DEQUEUE_OPTIONS_T”를 참고한다.
DEQUEUE_ARRAY 함수의 세부 내용은 다음과 같다.
프로토타입
DBMS_AQ.DEQUEUE_ARRAY
(
queue_name IN VARCHAR2,
dequeue_options IN DEQUEUE_OPTIONS_T,
array_size IN PLS_INTEGER,
message_properties_array OUT MESSAGE_PROPERTIES_ARRAY_T,
payload_array OUT PAYLOAD_ARRAY_T,
msgid_array OUT MSGID_ARRAY_T
)
RETURN pls_integer;
파라미터
| 파라미터 | 설명 |
|---|---|
| queue_name | 메시지들을 dequeue할 queue의 이름을 명시한다. |
| dequeue_options | dequeue할 모든 메시지에 동일하게 적용되는 옵션을 명시한다. 자세한 내용은 “5.2.3. DEQUEUE_OPTIONS_T”를 참고한다. |
| array_size | dequeue할 메시지의 수를 지정한다. |
| message_properties_array | 반환되는 메시지 속성들에 대한 배열이다. 자세한 내용은 “5.2.6. MESSAGE_PROPERTIES_ARRAY_T”를 참고한다. |
| payload_array | 반환되는 payload들에 대한 배열이다. 자세한 내용은 “5.2.8. PAYLOAD_ARRAY_T”를 참고한다. |
| msgid_array | dequeue된 메시지들의 메시지 식별자가 반환되는 배열이다. 자세한 내용은 “5.2.7. MSGID_ARRAY_T”를 참고한다. |
예제
declare
dequeue_options DBMS_AQ.dequeue_options_t;
msg_prop_array DBMS_AQ.message_properties_array_t;
payload_array dbms_aq.payload_array_t;
msgid_array DBMS_AQ.msgid_array_t;
retval PLS_INTEGER;
BEGIN
dequeue_options.consumer_name := 'RED';
retval := DBMS_AQ.DEQUEUE_ARRAY(
queue_name => 'my_multi_q',
dequeue_options => dequeue_options,
array_size => 10,
message_properties_array => msg_prop_array,
payload_array => payload_array,
msgid_array => msgid_array);
DBMS_OUTPUT.PUT_LINE('Number of messages dequeued: ' || retval);
for i in 1..retval loop
dbms_output.put_line ('msgid('||i||'): ' || msgid_array(i));
end loop;
END;
/
대상 queue에 메시지를 하나 enqueue한다. 복수 소비자 queue에 enqueue를 수행할 때 이 queue에 디폴트 구독자가 하나도 등록되어 있지 않은 상태에서 수신자를 명시하지 않으면 메시지를 전달할 곳이 없으므로 에러를 반환한다.
프로토타입
DBMS_AQ.ENQUEUE
(
queue_name IN VARCHAR2,
enqueue_options IN ENQUEUE_OPTIONS_T,
message_properties IN MESSAGE_PROPERTIES_T,
payload IN RAW,
msgid OUT RAW
);
파라미터
| 파라미터 | 설명 |
|---|---|
| queue_name | 메시지를 enqueue할 queue의 이름을 명시한다. |
| enqueue_options | enqueue할 모든 메시지에 동일하게 적용되는 옵션을 명시한다. 자세한 내용은 “5.2.4. ENQUEUE_OPTIONS_T”를 참고한다. |
| message_properties | enqueue할 메시지들의 메시지 속성을 명시한다. 자세한 내용은 “5.2.5. MESSAGE_PROPERTIES_T”를 참고한다. |
| payload | 사용자가 지정하는 payload이다. 현재는 RAW 타입만 가능하다. |
| msgid | 시스템이 부여한 메시지 식별자를 반환한다. 유일성이 보장되며 dequeue할 때 메시지 식별 용도로 사용 가능하다. |
예제
DECLARE
enqueue_options DBMS_AQ.enqueue_options_t;
message_properties DBMS_AQ.message_properties_t;
message_handle RAW(16);
BEGIN
message_properties.priority := 2;
message_properties.correlation := 'abc';
DBMS_AQ.ENQUEUE(
queue_name => 'my_q',
enqueue_options => enqueue_options,
message_properties => message_properties,
payload => hextoraw('FFFF'),
msgid => message_handle);
dbms_output.put_line('msgid: ' || message_handle);
END;
/
이 함수는 각각의 해당되는 메시지 속성과 함께 여러 payload를 한꺼번에 enqueue하는 함수이다. 완료와 함께 enqueue된 메시지의 식별자들을 담는 배열이 반환된다. 함수의 반환값은 성공적으로 enqueue된 메시지의 갯수이다.
ENQUEUE_ARRAY 함수의 세부 내용은 다음과 같다.
프로토타입
DBMS_AQ.ENQUEUE_ARRAY
(
queue_name IN VARCHAR2,
enqueue_options IN ENQUEUE_OPTIONS_T,
array_size IN PLS_INTEGER,
message_properties_array IN MESSAGE_PROPERTIES_ARRAY_T,
payload_array IN PAYLOAD_ARRAY_T,
msgid_array OUT MSGID_ARRAY_T
)
RETURN pls_integer;
파라미터
| 파라미터 | 설명 |
|---|---|
| queue_name | 메시지들을 enqueue할 queue의 이름을 명시한다. |
| enqueue_options | enqueue할 모든 메시지에 동일하게 적용되는 옵션을 명시한다. 자세한 내용은 “5.2.4. ENQUEUE_OPTIONS_T”를 참고한다. |
| array_size | enqueue할 메시지의 수를 지정한다. |
| message_properties_array | enqueue할 메시지들의 메시지 속성에 대한 배열이다. 자세한 내용은 “5.2.6. MESSAGE_PROPERTIES_ARRAY_T”를 참고한다. |
| payload_array | enqueue할 메시지들의 payload에 대한 배열이다. 자세한 내용은 “5.2.8. PAYLOAD_ARRAY_T”를 참고한다. |
| msgid_array | enqueue된 메시지들의 메시지 식별자가 반환되는 배열이다. 자세한 내용은 “5.2.7. MSGID_ARRAY_T”를 참고한다. |
예제
declare
v dbms_aq.payload_array_t;
msg_prop_array dbms_Aq.message_properties_array_t;
retval pls_integer;
msgid_array dbms_aq.msgid_array_t;
enqueue_options DBMS_AQ.enqueue_options_t;
begin
v := dbms_aq.payload_array_t (hextoraw('FFFF'), hextoraw('EEEE'),
hextoraw('EEEE'), hextoraw('EEEE'), hextoraw('EEEE'), hextoraw('EEEE'));
msg_prop_array := dbms_aq.message_properties_array_t ();
msg_prop_array.extend(6);
for i in 1..6 loop
msg_prop_array(i).priority := 7 - i;
end loop;
retval := dbms_aq.enqueue_array (
queue_name => 'my_multi_q',
enqueue_options => enqueue_options,
array_size => 6,
message_properties_array => msg_prop_array,
payload_array => v,
msgid_array => msgid_array);
dbms_output.put_line('processed: ' || retval);
for i in 1..retval loop
dbms_output.put_line ('msgid('||i||'): ' || msgid_array(i));
end loop;
end;
/