195 DBMS_XEVENT
The DBMS_XEVENTpackage provides event-related types and supporting subprograms.
This chapter contains the following topics:
See Also:
Oracle XML DB Developer's Guide for more information about "Oracle XML DB Repository Events"
195.1 DBMS_XEVENT Security Model
Owned by XDB
, the DBMS_XEVENT
package must be created by SYS
or XDB
. The EXECUTE
privilege is granted to PUBLIC
. Subprograms in this package are executed using the privileges of the current user.
195.2 DBMS_XEVENT Constants
The DBMS_XEVENT
package defines several constants that can be used for specifying parameter values.
The constants are defined in the following table.
Table 195-1 DBMS_XEVENT Constants
Name | Type | Value | Description |
---|---|---|---|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
4 |
|
|
|
|
|
|
|
6 |
|
|
|
|
|
|
|
8 |
|
|
|
|
|
|
|
10 |
|
|
|
|
|
|
|
12 |
|
|
|
13 |
|
|
|
14 |
|
|
|
|
|
|
|
16 |
|
|
|
|
|
|
|
|
|
|
|
19 |
|
|
|
|
|
|
|
21 |
|
|
|
22 |
|
|
|
23 |
|
|
|
24 |
|
|
|
25 |
|
|
|
26 |
|
|
|
27 |
|
|
|
28 |
|
|
|
29 |
|
|
|
30 |
|
|
|
21 |
|
|
|
21 |
195.3 Subprogram Groups
The subprograms in the DBMS_XEVENT
package can be divided in groups.
195.3.1 DBMS_XEVENT XDBEvent Type Subprograms
This subprogram group provides an interface for use with the XDBEvent type.
Table 195-2 XDBEvent Subprograms
Subprogram | Description |
---|---|
Returns the name of the user executing the operation that triggers the event |
|
Returns a value identifying the triggering event |
|
Returns |
The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.
195.3.2 DBMS_XEVENT XDBRepositoryEvent Type Subprograms
This subprogram group provides an interface for use in conjunction with the XDBRepositoryEvent type.
Table 195-3 XDBRepositoryEvent Subprograms
Subprogram | Description |
---|---|
Returns the |
|
Returns an |
|
Returns the top-level interface used to initiate the operation that triggered the event |
|
Returns an |
|
Returns the lock object corresponding to the current operation |
|
Returns the original |
|
Returns the access mode for the open operation |
|
Returns the deny mode for the open operation |
|
Returns the output BLOB in which the handler can write the rendered data |
|
Returns the value of a request or session-specific parameter |
|
Returns the resource object corresponding to a parent folder of the target resource |
|
Returns the |
|
Returns an |
|
If the current operation is a byte-range write, returns the byte count |
|
If the current operation is a byte-range write, function returns the byte offset at which the range begins |
|
Converts an |
|
Returns |
|
Specifies the path of the resource that contains the rendered contents |
|
sets the |
The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.
195.3.3 DBMS_XEVENT XDBHandlerList Type Subprograms
This subprogram group provides an interface for use in conjunction with the XDBHandlerList type.
Table 195-4 XDBHandlerList Subprograms
Subprogram | Description |
---|---|
Clears the handler list |
|
Returns the first handler in the list |
|
Returns the next handler in the list |
|
Returns |
|
Removes the specified handler from the handler list |
The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.
195.3.4 DBMS_XEVENT XDBHandler Type Subprograms
This subprogram group provides an interface for use in conjunction with the XDBHandler type.
Table 195-5 XDBHandler Type Subprograms
Subprogram | Description |
---|---|
Returns the implementation language of the handler |
|
Returns the schema of the handler's source |
|
Returns the name of the Java class, PL/SQL package or object type implementing the handler |
|
Returns |
The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.
195.3.5 DBMS_XEVENT XDBPath Type Subprograms
This subprogram group provides an interface for use in conjunction with the XDBPath type.
Table 195-6 XDBPath Type Subprograms
Subprogram | Description |
---|---|
Returns the string representation of the path |
|
Returns the parent's path |
|
Returns |
The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.
195.3.6 DBMS_XEVENT XDBLink Type Subprograms
This subprogram group provides an interface for use in conjunction with the XDBLink type.
Table 195-7 XDBLink Type Subprograms
Subprogram | Description |
---|---|
Returns the OID of the resource to which the link is pointing |
|
Returns the link's parent folder's name |
|
Returns the link's parent folder's OID |
|
Returns |
The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.
195.4 Summary of DBMS_XEVENT Subprograms
This table lists the DBMS_XEVENT subprograms and briefly describes them.
Table 195-8 DBMS_XEVENT Package Subprograms
Subprogram | Description | Group |
---|---|---|
Clears the handler list |
||
Returns the |
||
Returns the OID of the resource to which the link is pointing |
||
Returns the name of the user executing the operation that triggers the event |
||
Returns a value identifying the triggering event |
||
Returns the first handler in the list |
||
Returns an |
||
Returns the top-level interface used to initiate the operation that triggered the event |
||
Returns the implementation language of the handler |
||
Returns an |
||
Returns the lock object corresponding to the current operation |
||
Returns the string representation of the path |
||
Returns the next handler in the list |
||
Returns the original |
||
Returns the access mode for the open operation |
||
Returns the deny mode for the open operation |
||
Returns the output BLOB in which the handler can write the rendered data |
||
Returns the value of a request or session-specific parameter |
||
Returns the resource object corresponding to a parent folder of the target resource |
||
Returns the link's parent folder's name |
||
Returns the link's parent folder's OID |
||
Returns the parent's path |
||
Returns the |
||
Returns an |
||
Returns the schema of the handler's source |
||
Returns the name of the Java class, PL/SQL package or object type implementing the handler |
||
If the current operation is a byte-range write, returns the byte count |
||
If the current operation is a byte-range write, function returns the byte offset at which the range begins |
||
Converts an |
||
Returns |
XDBRepositoryEvent Type Subprograms |
|
Removes the specified handler from the handler list |
||
Specifies the path of the resource that contains the rendered contents |
||
sets the |
195.4.1 CLEAR Procedure
This procedure clears the handler list.
See Also:
XDBHandlerList Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.CLEAR ( hl IN OUT XDBHandlerList);
Parameters
Table 195-9 CLEAR Procedure Parameters
Parameter | Description |
---|---|
|
Handler list |
195.4.2 GETAPPLICATIONDATA Function
This function returns the <applicationData>
element extracted from the resource configuration that defines the invoking handler.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETAPPLICATIONDATA ( ev IN XDBRepositoryEvent) RETURN XMLType;
Parameters
Table 195-10 GETAPPLICATIONDATA Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.3 GETCHILDOID Function
This function returns the OID of the resource to which the link is pointing.
See Also:
XDBLink Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETCHILDOID ( link IN XDBLink) RETURN RAW;
Parameters
Table 195-11 GETCHILDOID Function Parameters
Parameter | Description |
---|---|
|
Link |
195.4.4 GETCURRENTUSER Function
This function returns the name of the user executing the operation that triggers the event.
See Also:
XDBEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETCURRENTUSER ( ev IN XDBEvent) RETURN VARCHAR2;
Parameters
Table 195-12 GETCURRENTUSER Function Parameters
Parameter | Description |
---|---|
|
Event of XDBEvent type |
195.4.5 GETEVENT Function
This function returns the name of the user executing the operation that triggers the event.
See Also:
XDBEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETEVENT ( ev IN XDBEvent) RETURN XDBEventID;
Parameters
Table 195-13 GETEVENT Function Parameters
Parameter | Description |
---|---|
|
Event of XDBEvent type |
195.4.6 GETFIRST Function
This function returns the first handler in the list.
See Also:
XDBHandlerList Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETFIRST ( hl IN XDBHandlerList) RETURN XDBHandler;
Parameters
Table 195-14 GETFIRST Function Parameters
Parameter | Description |
---|---|
|
Handler list |
195.4.7 GETHANDLERLIST Function
This function returns an XDBHandlerList
object containing the list of handlers that will be executed after the currently executing handler.
The current handler can then filter out some of the subsequent handlers if necessary, subject to security checks. An insufficient privilege exception is raised if the executing user does not have the required access privilege to any of the resource configuration associating with a handler in the list.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETHANDLERLIST ( ev IN XDBRepositoryEvent) RETURN XDBHandlerList;
Parameters
Table 195-15 GETHANDLERLIST Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.8 GETINTERFACE Function
This function returns the top-level interface used to initiate the operation that triggered the event. This could be HTTP, FTP or SQL.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETINTERFACE ( ev IN XDBRepositoryEvent) RETURN VARCHAR2;
Parameters
Table 195-16 GETINTERFACE Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.9 GETLANGUAGE Function
This function returns the implementation language of the handler.
See Also:
XDBHandler Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETLANGUAGE ( handler IN XDBHandler) RETURN VARCHAR2;
Parameters
Table 195-17 GETLANGUAGE Function Parameters
Parameter | Description |
---|---|
handler |
Handler |
195.4.10 GETLINK Function
This function returns an XDBLink
object for the target resource.
For a link* or unlink* event, this will be the link involved in the operation. For other events, an error is returned. Using this object the handler can access link properties, such as, ParentName
, ParentOID
, ChildOID
and LinkName
.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETLINK ( ev IN XDBRepositoryEvent) RETURN XDBLink;
Parameters
Table 195-18 GETLINK Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.11 GETLINKNAME Function
This function returns the name of the link.
See Also:
XDBLink Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETLINKNAME ( link IN XDBLink) RETURN VARCHAR2;
Parameters
Table 195-19 GETLINKNAME Function Parameters
Parameter | Description |
---|---|
|
Link |
195.4.12 GETLOCK Function
This function returns the lock object corresponding to the current operation.I t is only valid for lock and unlock events.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETLOCK ( ev IN XDBRepositoryEvent) RETURN XDBLock;
Parameters
Table 195-20 GETLOCK Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.13 GETLANGUAGE Function
This function returns the implementation language of the handler.
See Also:
XDBHandler Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETLANGUAGE ( handler IN XDBHandler) RETURN VARCHAR2;
Parameters
Table 195-21 GETLANGUAGE Function Parameters
Parameter | Description |
---|---|
handler |
Handler |
195.4.14 GETNAME Function
This function returns the string representation of the path.
See Also:
XDBPath Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETNAME ( path IN XDBPath) RETURN VARCHAR2;
Parameters
Table 195-22 GETNAME Function Parameters
Parameter | Description |
---|---|
|
Path |
195.4.15 GETNEXT Function
This function returns the next handler in the list.
See Also:
XDBHandlerList Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETNEXT ( hl IN XDBHandlerList) RETURN XDBHandler;
Parameters
Table 195-23 GETNEXT Function Parameters
Parameter | Description |
---|---|
|
Handler list |
195.4.16 GETOLDRESOURCE Function
This function returns the original XDBResource
object before the operation was executed.
This method applies only to update event. For other events, an error is returned. This is a read-only object, and consequently none of the modifier methods will work on this object.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETOLDRESOURCE ( ev IN XDBRepositoryEvent) RETURN XDBResource;
Parameters
Table 195-24 GETOLDRESOURCE Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.17 GETOPENACCESSMODE Function
This function returns the access mode for the open operation.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETOPENACCESSMODE ( ev IN XDBRepositoryEvent) RETURN PLS_INTEGER;
Parameters
Table 195-25 GETOPENACCESSMODE Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
Return Values
-
XDBRepositoryEvent
.OPEN_ACCESS_READ
(value 1) -
XDBRepositoryEvent
.OPEN_ACCESS_WRITE
(value 2) -
XDBRepositoryEvent
.OPEN_ACCESS_READ_WRITE
(value 3)
195.4.18 GETOPENDENYMODE Function
This function returns the deny mode for the open operation. It is only valid for the open event.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETOPENDENYMODE ( ev IN XDBRepositoryEvent) RETURN PLS_INTEGER;
Parameters
Table 195-26 GETOPENDENYMODE Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
Return Values
-
XDBRepositoryEvent
.OPEN_DENY_NONE
(value 0) -
XDBRepositoryEvent
.OPEN_DENY_READ
(value 1) -
XDBRepositoryEvent
.OPEN_DENY_READ_WRITE
(value 2)
195.4.19 GETOUTPUTSTREAM Function
This function returns the output BLOB in which the handler can write the rendered data. It is only valid for the render event.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETOUTPUTSTREAM ( ev IN XDBRepositoryEvent) RETURN BLOB;
Parameters
Table 195-27 GETOUTPUTSTREAM Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.20 GETPARAMETER Function
This function returns the value of a request or session-specific parameter. The definition of the key
parameter can be found in RFC 2616 (HTTP/1.1). They will be mapped to equivalent SQL session parameters (if any).
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETPARAMETER ( ev IN XDBRepositoryEvent, key IN VARCHAR2) RETURN VARCHAR2;
Parameters
Table 195-28 GETPARAMETER Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
key |
Supported parameters:
|
195.4.21 GETPARENT Function
This function returns the resource object corresponding to a parent folder of the target resource. Note that this could be any folder that contains a link to the target resource. This is a read-only object, and consequently none of the modifier methods will work on this object. For a link* or unlink* event, this method returns the link's parent folder.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETPARENT ( ev IN XDBRepositoryEvent) RETURN XDBResource;
Parameters
Table 195-29 GETPARENT Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.22 GETPARENTNAME Function
This function returns the link's parent folder's name.
See Also:
XDBLink Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETPARENTNAME ( link IN XDBLink) RETURN VARCHAR2;
Parameters
Table 195-30 GETPARENTNAME Function Parameters
Parameter | Description |
---|---|
|
Link |
195.4.23 GETPARENTOID Function
This function returns the link's parent folder's OID.
See Also:
XDBLink Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETPARENTOID ( link IN XDBLink) RETURN RAW;
Parameters
Table 195-31 GETPARENTOID Function Parameters
Parameter | Description |
---|---|
|
Link |
195.4.24 GETPARENTPATH Function
This function returns the parent's path. The level indicates the number of levels up the hierarchy. This value must be greater than zero. Level 1 means the immediate parent. If level exceeds the height of the tree then a NULL
is returned.
See Also:
XDBPath Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETPARENTPATH ( path IN XDBPath, level IN INTEGER) RETURN XDBPath;
Parameters
Table 195-32 GETPARENTPATH Function Parameters
Parameter | Description |
---|---|
|
Path |
|
Number of levels up the hierarchy |
195.4.25 GETPATH Function
This function returns the XDBPath
object representing the path of the resource for which the event was fired. From this object, functions are provided to get the different path segments.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETPATH ( ev IN XDBRepositoryEvent) RETURN XDBPath;
Parameters
Table 195-33 GETPATH Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.26 GETRESOURCE Function
This function returns an XDBResource
object that provides methods to access and modify the contents and metadata of the target resource. This object reflects any changes made by previous handlers to the resource.
The modifier methods will work only in the pre-create and pre-update event handlers. For a link* or unlink* event, this method returns the resource that the link is pointing to. For a create event, this method returns the resource that is being created.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETRESOURCE ( ev IN XDBRepositoryEvent) RETURN XDBResource;
Parameters
Table 195-34 GETRESOURCE Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.27 GETSCHEMA Function
This function returns the schema of the handler's source.
See Also:
XDBHandler Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETSCHEMA ( handler IN XDBHandler) RETURN VARCHAR2;
Parameters
Table 195-35 GETSCHEMA Function Parameters
Parameter | Description |
---|---|
handler |
Handler |
195.4.28 GETSOURCE Function
This function returns the name of the Java class, PL/SQL package or object type implementing the handler.
See Also:
XDBHandler Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETSOURCE ( handler IN XDBHandler) RETURN VARCHAR2;
Parameters
Table 195-36 GETSOURCE Function Parameters
Parameter | Description |
---|---|
handler |
Handler |
195.4.29 GETUPDATEBYTECOUNT Function
If the current operation is a byte-range write, the GETUPDATEBYTECOUNT
function returns the byte count. It is only valid for the inconsistent-update event.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETUPDATEBYTECOUNT ( ev IN XDBRepositoryEvent) RETURN NUMBER;
Parameters
Table 195-37 GETUPDATEBYTECOUNT Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.30 GETUPDATEBYTEOFFSET Function
If the current operation is a byte-range write, the GETUPDATEBYTEOFFSET
function returns the byte offset at which the range begins. It is only valid for the inconsistent-update event.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETUPDATEBYTEOFFSET ( ev IN XDBRepositoryEvent) RETURN NUMBER;
Parameters
Table 195-38 GETUPDATEBYTEOFFSET Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.31 GETXDBEVENT Function
This function converts an XDBRepositoryEvent
object to an XDBEvent
type.
See Also:
XDBRepositoryEvent Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.GETXDBETEVENT ( ev IN XDBRepositoryEvent) RETURN XDBEvent;
Parameters
Table 195-39 GETXDBEVENT Function Parameters
Parameter | Description |
---|---|
|
Event of XDBRepositoryEvent type |
195.4.32 ISNULL Functions
This function returns TRUE
if input argument is NULL
.
See Also:
-
XDBEvent Type Subprograms for other subprograms in this group
-
XDBRepositoryEvent Type Subprograms for other subprograms in this group
-
XDBHandlerList Type Subprograms for other subprograms in this group
-
XDBHandler Type Subprograms for other subprograms in this group
-
XDBPath Type Subprograms for other subprograms in this group
-
XDBLink Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.ISNULL ( ev IN XDBEvent) RETURN BOOLEAN; DBMS_XEVENT.ISNULL ( ev IN XDBRepositoryEvent) RETURN BOOLEAN; DBMS_XEVENT.ISNULL ( hl IN XDBHandlerList) RETURN BOOLEAN; DBMS_XEVENT.ISNULL ( handler IN XDBHandler) RETURN BOOLEAN; RETURN BOOLEAN; DBMS_XEVENT.ISNULL ( path IN XDBPath) RETURN BOOLEAN; DBMS_XEVENT.ISNULL ( link IN XDBLink) RETURN BOOLEAN;
Parameters
Table 195-40 ISNULL Function Parameters
Parameter | Description |
---|---|
|
Event of specified type |
|
Handler list |
|
Handler |
|
Path |
195.4.33 REMOVE Procedure
This procedure removes the specified handler from the handler list.
See Also:
XDBHandlerList Type Subprograms for other subprograms in this group
Syntax
DBMS_XEVENT.REMOVE ( hl IN OUT XDBHandlerList, handler IN XDBHandler);
Parameters
Table 195-41 REMOVE Procedure Parameters
Parameter | Description |
---|---|
|
Handler list |
|
Handler |
195.4.34 SETRENDERPATH Procedure
This procedure specifies the path of the resource that contains the rendered contents.
This should not be called after the stream returned by GETOUTPUTSTREAM Function is written to or after the SETRENDERSTREAM Procedure is called; doing so will result in an error. This is only valid for the render event.
Syntax
DBMS_XEVENT.SETRENDERPATH ( ev IN XDBRepositoryEvent, path IN VARCHAR2);
Parameters
Table 195-42 SETRENDERPATH Procedure Parameters
Parameter | Description |
---|---|
|
XDB Repository Event object |
|
Path of the resource containing the rendered contents |
195.4.35 SETRENDERSTREAM Procedure
This procedure sets the BLOB
from which the rendered contents can be read.
This should not be called after the stream returned by GETOUTPUTSTREAM is written to or after SETRENDERPATH is called; doing so will result in an error. This is only valid for the render event.
Syntax
DBMS_XEVENT.SETRENDERSTREAM ( ev IN XDBRepositoryEvent, istr IN BLOB);
Parameters
Table 195-43 SETRENDERSTREAM Procedure Parameters
Parameter | Description |
---|---|
|
XDBRepositoryEvent object |
|
Input stream from which to get the rendered contents |