169 DBMS_XEVENT

Using DBMS_XEVENT

• Security Model

• Constants

---

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.

---

Constants

The DBMS_XEVENT package uses the constants shown in Table 169-1:

Subprogram Groups

• XDBEvent Type Subprograms

• XDBRepositoryEvent Type Subprograms

• XDBHandlerList Type Subprograms

• XDBHandler Type Subprograms

• XDBPath Type Subprograms

• XDBLink Type Subprograms

---

XDBEvent Type Subprograms

This subprogram group provides an interface for use in conjunction with the XDBEvent type.

The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.

---

XDBRepositoryEvent Type Subprograms

This subprogram group provides an interface for use in conjunction with the XDBRepositoryEvent type.

The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.

---

XDBHandlerList Type Subprograms

This subprogram group provides an interface for use in conjunction with the XDBHandlerList type.

The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.

---

XDBHandler Type Subprograms

This subprogram group provides an interface for use in conjunction with the XDBHandler type.

The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.

---

XDBPath Type Subprograms

This subprogram group provides an interface for use in conjunction with the XDBPath type.

The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.

---

XDBLink Type Subprograms

This subprogram group provides an interface for use in conjunction with the XDBLink type.

The Summary of DBMS_XEVENT Subprograms contains a complete listing of all subprograms in the package.

Summary of DBMS_XEVENT Subprograms

---

CLEAR Procedure

this procedure clears the handler list.

Syntax

DBMS_XEVENT.CLEAR (
    hl       IN OUT   XDBHandlerList);

Parameters

---

GETAPPLICATIONDATA Function

This function returns the <applicationData> element extracted from the resource configuration that defines the invoking handler.

Syntax

DBMS_XEVENT.GETAPPLICATIONDATA (
    ev   IN   XDBRepositoryEvent) 
  RETURN XMLType;

Parameters

---

GETCHILDOID Function

This function returns the OID of the resource to which the link is pointing.

Syntax

DBMS_XEVENT.GETCHILDOID (
    link   IN   XDBLink) 
  RETURN RAW;

Parameters

---

GETCURRENTUSER Function

This function returns the name of the user executing the operation that triggers the event.

Syntax

DBMS_XEVENT.GETCURRENTUSER (
    ev   IN   XDBEvent) 
  RETURN VARCHAR2;

Parameters

---

GETEVENT Function

This function returns the name of the user executing the operation that triggers the event.

Syntax

DBMS_XEVENT.GETEVENT (
    ev   IN   XDBEvent) 
  RETURN XDBEventID;

Parameters

---

GETFIRST Function

This function returns the first handler in the list.

Syntax

DBMS_XEVENT.GETFIRST (
    hl   IN   XDBHandlerList) 
  RETURN XDBHandler;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETHANDLERLIST (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBHandlerList;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETINTERFACE (
    ev   IN   XDBRepositoryEvent) 
  RETURN VARCHAR2;

Parameters

---

GETLANGUAGE Function

This function returns the implementation language of the handler.

Syntax

DBMS_XEVENT.GETLANGUAGE (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETLINK (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBLink;

Parameters

---

GETLINKNAME Function

This function returns the name of the link.

Syntax

DBMS_XEVENT.GETLINKNAME (
    link   IN   XDBLink) 
  RETURN VARCHAR2;

Parameters

---

GETLOCK Function

This function returns the lock object corresponding to the current operation.I t is only valid for lock and unlock events.

Syntax

DBMS_XEVENT.GETLOCK  (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBLock;

Parameters

---

GETLANGUAGE Function

This function returns the implementation language of the handler.

Syntax

DBMS_XEVENT.GETLANGUAGE (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

Parameters

---

GETNAME Function

This function returns the string representation of the path.

Syntax

DBMS_XEVENT.GETNAME (
    path   IN   XDBPath) 
  RETURN VARCHAR2;

Parameters

---

GETNEXT Function

This function returns the next handler in the list.

Syntax

DBMS_XEVENT.GETNEXT (
    hl   IN   XDBHandlerList) 
  RETURN XDBHandler;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETOLDRESOURCE (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBResource;

Parameters

---

GETOPENACCESSMODE Function

This function returns the access mode for the open operation.

Syntax

DBMS_XEVENT.GETOPENACCESSMODE (
    ev   IN   XDBRepositoryEvent) 
  RETURN PLS_INTEGER;

Parameters

Return Values

• XDBRepositoryEvent.OPEN_ACCESS_READ (value 1)

• XDBRepositoryEvent.OPEN_ACCESS_WRITE (value 2)

• XDBRepositoryEvent.OPEN_ACCESS_READ_WRITE (value 3)

---

GETOPENDENYMODE Function

This function returns the deny mode for the open operation. It is only valid for the open event.

Syntax

DBMS_XEVENT.GETOPENDENYMODE (
    ev   IN   XDBRepositoryEvent) 
  RETURN PLS_INTEGER;

Parameters

Return Values

• XDBRepositoryEvent.OPEN_DENY_NONE (value 0)

• XDBRepositoryEvent.OPEN_DENY_READ (value 1)

• XDBRepositoryEvent.OPEN_DENY_READ_WRITE (value 2)

---

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.

Syntax

DBMS_XEVENT.GETOUTPUTSTREAM (
    ev   IN   XDBRepositoryEvent) 
  RETURN BLOB;

Parameters

---

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).

Syntax

DBMS_XEVENT.GETPARAMETER (
    ev   IN   XDBRepositoryEvent,
    key  IN   VARCHAR2) 
  RETURN VARCHAR2;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETPARENT (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBResource;

Parameters

---

GETPARENTNAME Function

This function returns the link's parent folder's name.

Syntax

DBMS_XEVENT.GETPARENTNAME (
    link   IN   XDBLink) 
  RETURN VARCHAR2;

Parameters

---

GETPARENTOID Function

This function returns the link's parent folder's OID.

Syntax

DBMS_XEVENT.GETPARENTOID (
    link   IN   XDBLink) 
  RETURN RAW;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETPARENTPATH (
    path   IN   XDBPath,
   level   IN   INTEGER) 
  RETURN XDBPath;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETPATH (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBPath;

Parameters

---

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.

Syntax

DBMS_XEVENT.GETRESOURCE (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBResource;

Parameters

---

GETSCHEMA Function

This function returns the schema of the handler's source.

Syntax

DBMS_XEVENT.GETSCHEMA (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

Parameters

---

GETSOURCE Function

This function returns the name of the Java class, PL/SQL package or object type implementing the handler.

Syntax

DBMS_XEVENT.GETSOURCE (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

Parameters

---

GETUPDATEBYTECOUNT Function

If the current operation is a byte-range write, the function returns the byte count. It is only valid for the inconsistent-update event.

Syntax

DBMS_XEVENT.GETUPDATEBYTECOUNT (
    ev   IN   XDBRepositoryEvent) 
  RETURN NUMBER;

Parameters

---

GETUPDATEBYTEOFFSET Function

If the current operation is a byte-range write, function returns the byte offset at which the range begins. It is only valid for the inconsistent-update event.

Syntax

DBMS_XEVENT.GETUPDATEBYTEOFFSET (
    ev   IN   XDBRepositoryEvent) 
  RETURN NUMBER;

Parameters

---

GETXDBEVENT Function

This function converts an XDBRepositoryEvent object to an XDBEvent type.

Syntax

DBMS_XEVENT.GETXDBETEVENT (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBEvent;

Parameters

---

ISNULL Functions

This function returns TRUE if input argument is NULL.

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

---

REMOVE Procedure

This procedure removes the specified handler from the handler list.

Syntax

DBMS_XEVENT.REMOVE (
    hl       IN OUT   XDBHandlerList, 
    handler  IN       XDBHandler);

Parameters

---

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

---

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