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

Constants

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

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.

CLEAR Procedure

this procedure clears the handler list.

DBMS_XEVENT.CLEAR (
    hl       IN OUT   XDBHandlerList);

GETAPPLICATIONDATA Function

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

DBMS_XEVENT.GETAPPLICATIONDATA (
    ev   IN   XDBRepositoryEvent) 
  RETURN XMLType;

GETCHILDOID Function

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

DBMS_XEVENT.GETCHILDOID (
    link   IN   XDBLink) 
  RETURN RAW;

GETCURRENTUSER Function

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

DBMS_XEVENT.GETCURRENTUSER (
    ev   IN   XDBEvent) 
  RETURN VARCHAR2;

GETEVENT Function

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

DBMS_XEVENT.GETEVENT (
    ev   IN   XDBEvent) 
  RETURN XDBEventID;

GETFIRST Function

This function returns the first handler in the list.

DBMS_XEVENT.GETFIRST (
    hl   IN   XDBHandlerList) 
  RETURN XDBHandler;

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.

DBMS_XEVENT.GETHANDLERLIST (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBHandlerList;

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.

DBMS_XEVENT.GETINTERFACE (
    ev   IN   XDBRepositoryEvent) 
  RETURN VARCHAR2;

GETLANGUAGE Function

This function returns the implementation language of the handler.

DBMS_XEVENT.GETLANGUAGE (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

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.

DBMS_XEVENT.GETLINK (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBLink;

GETLINKNAME Function

This function returns the name of the link.

DBMS_XEVENT.GETLINKNAME (
    link   IN   XDBLink) 
  RETURN VARCHAR2;

GETLOCK Function

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

DBMS_XEVENT.GETLOCK  (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBLock;

GETLANGUAGE Function

This function returns the implementation language of the handler.

DBMS_XEVENT.GETLANGUAGE (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

GETNAME Function

This function returns the string representation of the path.

DBMS_XEVENT.GETNAME (
    path   IN   XDBPath) 
  RETURN VARCHAR2;

GETNEXT Function

This function returns the next handler in the list.

DBMS_XEVENT.GETNEXT (
    hl   IN   XDBHandlerList) 
  RETURN XDBHandler;

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.

DBMS_XEVENT.GETOLDRESOURCE (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBResource;

GETOPENACCESSMODE Function

This function returns the access mode for the open operation.

DBMS_XEVENT.GETOPENACCESSMODE (
    ev   IN   XDBRepositoryEvent) 
  RETURN PLS_INTEGER;

GETOPENDENYMODE Function

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

DBMS_XEVENT.GETOPENDENYMODE (
    ev   IN   XDBRepositoryEvent) 
  RETURN PLS_INTEGER;

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.

DBMS_XEVENT.GETOUTPUTSTREAM (
    ev   IN   XDBRepositoryEvent) 
  RETURN BLOB;

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

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

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.

DBMS_XEVENT.GETPARENT (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBResource;

GETPARENTNAME Function

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

DBMS_XEVENT.GETPARENTNAME (
    link   IN   XDBLink) 
  RETURN VARCHAR2;

GETPARENTOID Function

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

DBMS_XEVENT.GETPARENTOID (
    link   IN   XDBLink) 
  RETURN RAW;

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.

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

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.

DBMS_XEVENT.GETPATH (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBPath;

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.

DBMS_XEVENT.GETRESOURCE (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBResource;

GETSCHEMA Function

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

DBMS_XEVENT.GETSCHEMA (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

GETSOURCE Function

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

DBMS_XEVENT.GETSOURCE (
    handler   IN   XDBHandler) 
  RETURN VARCHAR2;

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.

DBMS_XEVENT.GETUPDATEBYTECOUNT (
    ev   IN   XDBRepositoryEvent) 
  RETURN NUMBER;

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.

DBMS_XEVENT.GETUPDATEBYTEOFFSET (
    ev   IN   XDBRepositoryEvent) 
  RETURN NUMBER;

GETXDBEVENT Function

This function converts an XDBRepositoryEvent object to an XDBEvent type.

DBMS_XEVENT.GETXDBETEVENT (
    ev   IN   XDBRepositoryEvent) 
  RETURN XDBEvent;

ISNULL Functions

This function returns TRUE if input argument is NULL.

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;

REMOVE Procedure

This procedure removes the specified handler from the handler list.

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

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.

DBMS_XEVENT.SETRENDERPATH (
    ev     IN   XDBRepositoryEvent, 
    path   IN   VARCHAR2);

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.

DBMS_XEVENT.SETRENDERSTREAM (
    ev    IN   XDBRepositoryEvent, 
    istr  IN   BLOB);