Skip Headers

Oracle Internet Directory Application Developer's Guide
Release 9.2

Part Number A96577-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

9
Oracle Internet Directory Server Plug-in Framework

This chapter explains how to use the plug-in framework for the Oracle Internet Directory server to facilitate custom development.

This chapter contains these topics:

Introduction

The plug-in framework for Oracle Internet Directory enables developers to extend LDAP operations. For example:

Prerequisite Knowledge

In order to develop Oracle Internet Directory plug-ins you should be familiar with:

Concepts

This section explains plug-in concepts.

This section contains these topics:

About Directory Server Plug-ins

To extend the capabilities of the Oracle Internet Directory server, you can write your own server plug-in. A server plug-in is a PL/SQL package, shared object or library, or a dynamic link library on Windows NT, containing your own functions. (Currently, we support PL/SQL.)

You can write your own plug-in functions to extend the functionality of the Oracle Internet Directory server using the following methods:

On startup, the directory server loads your plug-in configuration and library, and calls your plug-in functions during the course of processing various LDAP requests.

About Server Plug-in Framework

Oracle Internet Directory server plug-in framework is the environment in which the plug-in user can develop, configure, and apply the plug-ins. Each individual plug-in instance is called a plug-in module.

The plug-in framework includes the following:

The steps to use the server plug-in framework are as follows:

  1. Write a user-defined plug-in procedure. This plug-in module must be written in PL/SQL.


    Note:

    The PL/SQL language is currently supported.


  2. Compile the plug-in module against the same database which serves as the Oracle Internet Directory backend database.
  3. Grant execute permission of the plug-in module to ods_server.
  4. Register the plug-in module through the configuration entry interface where the following are specified:
    • Names of the plug-ins
    • Type of the plug-ins
  5. Restart the LDAP server.

Figure 9-1 Oracle Internet Directory Server Plug-in Framework

Text description of oiddg010.gif follows
Text description of the illustration oiddg010.gif


Operation-Based Plug-ins Supported in Oracle Internet Directory

For operation-based plug-ins, there are pre-operation, post-operation, and when-operation plug-ins.

Pre-Operation Plug-ins

The server calls pre-operation plug-in modules before performing the LDAP operation. The main purpose of this type of plug-in is to validate data before the data can be used in the LDAP operation.

When an exception occurs in the pre-operation plug-in, one of the following occurs:

If the associated LDAP request fails later on, then Oracle Internet Directory server does not rollback the committed code in the plug-in modules.

Post-Operation Plug-ins

The Oracle Internet Directory server calls post-operation plug-in modules after performing an LDAP operation. The main purpose of this type of plug-in is to invoke a function after a particular operation is executed. For example, logging and notification are post-operation plug-in functions.

When an exception occurs in the post-operation plug-in, the associated LDAP operation is not be rolled back.

If the associated LDAP request fails, then the post plug-in will still be executed.

When-Operation Plug-ins

The server calls when-operation plug-in modules in addition to standard processing. The main purpose of this type of plug-in is to augment existing functionality. Any extra operations that need to be thought of as part of an LDAP operation, that is, in the same LDAP transaction, must use the WHEN option. The when-operation plug-in is essentially in the same transaction as the associated LDAP request. If either the LDAP request or the plug-in program fails, then all the changes are rolled back.

There are different types of When-operation plug-ins.

For example, for the ldapcompare operation, you can use the When Add-on type plug-in. Oracle Internet Directory server executes its server compare code and executes the plug-in module defined by the plug-in developer. For the When Replace plug-in, Oracle Internet Directory does not execute its own compare code and relies on the plug-in module to do the comparison and pass back the compare result. The server comparison procedures are replaced by the plug-in module.

When Replace operation plug-ins are only supported in ldapcompare and ldapmodify. When Add-on plug-ins are supported in ldapadd, ldapdelete, ldapmodify, ldapcompare, ldapbind, and ldapsearch.

Requirements

This section explains requirements for plug-ins.

This section contains these topics:

Designing Plug-ins

Use the following guidelines when designing plug-ins:

Types of Plug-in Operations

A plug-in can be associated with ldapbind, ldapadd, ldapmodify, ldapcompare, ldapsearch, and ldapdelete operations.

Naming Plug-ins

Plug-in names (PL/SQL package names) must be unique with respect to other plug-ins or stored procedures in the same database schema. Plug-in names do not need to be unique with respect to other database schema objects, such as tables and views. For example, a database table and a plug-in can have the same name (however, to avoid confusion, this is not recommended).

Creating Plug-ins

The process to create a plug-in module is the same as to create a PL/SQL package. There is a plug-in specification part and a plug-in body part. Oracle Internet Directory defines the plug-in specification because the specification serves as the interface between Oracle Internet Directory server and custom plug-ins.

For security purposes and for the integrity of the LDAP server, plug-ins can only be compiled in ODS database schema against the database which serves as the backend database of the Oracle Internet Directory server.

Plug-in Module Interface Package Specifications

For different types of plug-ins, there are different package specifications defined. You can name the plug-in package. However, you must follow the signatures defined for each type of plug-in procedure.

Table 9-1  Plug-in Module Interface
Plug-in Item User Defined Oracle Internet Directory-Defined

Plug-in Package Name

X

-

Plug-in Procedure Name

-

X

Plug-in Procedure Signature

-

X

See Also:

Plug-in Module Interface Specifications andUsage Model and Examples for coding examples

The following table shows the parameters for different kinds of operation-based plug-ins.

Table 9-2  Operation-Based and Attribute-Based Plug-in Procedure Signatures
Invocation Context Procedure Name IN Parameters OUT Parameters

Before ldapbind

PRE_BIND

Ldapcontext, Bind DN, Password

Return code, Error message

With ldapbind

WHEN_BIND

Ldapcontext, Bind DN, Password

Return code, Error message

After ldapbind

POST_BIND

Ldapcontext, Bind result, Bind DN, Password

Return code, Error message

Before ldapmodify

PRE_MODIFY

Ldapcontext, DN, Mod structure

Return code, Error message

With ldapmodify

WHEN_MODIFY

Ldapcontext, DN, Mod structure

Return code, Error message

With ldapmodify but replacing the default server behavior

WHEN_MODIFY_REPLACE

Ldapcontext, DN, Mod structure

Return code, Error message

After ldapmodify

POST_MODIFY

Ldapcontext, Modify result, DN, Mod structure

return code, error message

Before ldapcompare

PRE_COMPARE

Ldapcontext, DN, attribute, value

return code, error message

With ldapcompare

WHEN_COMPARE

Ldapcontext, DN, attribute, value

return code, error message

With ldapcompare but replacing the default server behavior

WHEN_COMPARE_REPLACE

Ldapcontext, Compare result, DN, attribute, value

compare result, return code, error message

After ldapcompare

POST_COMPARE

Ldapcontext, Compare result, DN, attribute, value

return code, error message

Before ldapadd

PRE_ADD

Ldapcontext, Entry

return code, error message

With ldapadd

WHEN_ADD

Ldapcontext, Entry

return code, error message

After ldapadd

POST_ADD

Ldapcontext, Add result, Entry

return code, error message

Before ldapdelete

PRE_DELETE

Ldapcontext, DN

return code, error message

With ldapdelete

WHEN_DELETE

Ldapcontext, DN

return code, error message

After ldapdelete

POST_DELETE

Ldapcontext, Delete result, DN

return code, error message

Before ldapsearch

PRE_SEARCH

Ldapcontext, Base DN, scope, filter

return code, error message

With ldapsearch

WHEN_SEARCH

Ldapcontext, Base DN, scope, filter

return code, error message

After ldapsearch

POST_SEARCH

Ldap context, Search result, Base DN, scope, filter

return code, error message

See Also:

Compiling Plug-ins

Plug-ins are exactly the same as PL/SQL stored procedures. A PL/SQL anonymous block is compiled each time it is loaded into memory. Compilation involves the following stages:

  1. Syntax checking: PL/SQL syntax is checked, and a parse tree is generated.
  2. Semantic checking: Type checking and further processing on the parse tree.
  3. Code generation: The pcode is generated.

If errors occur during the compilation of a plug-in, then the plug-in is not created. You can use the SHOW ERRORS statement in SQL*Plus or Enterprise Manager to see any compilation errors when you create a plug-in, or you can SELECT the errors from the USER_ERRORS view.

All plug-in modules must be compiled in the ODS database schema.

Dependencies

Compiled plug-ins have dependencies. They become invalid if an object depended upon, such as a stored procedure or function called from the plug-in body, is modified. Plug-ins that are invalidated for dependency reasons must be recompiled before the next invocation.

Recompiling Plug-ins

Use the ALTER PACKAGE statement to manually recompile a plug-in. For example, the following statement recompiles the my_plugin plug-in:

ALTER PACKAGE my_plugin COMPILE PACKAGE;

Granting Permission

Use the GRANT EXECUTE statement to grant execute permission to ods_server for the plug-in modules.

Registering Plug-ins

To enable the directory server to call a plug-in at the right moment, you must register the plug-in with the directory server. Do this by creating an entry for the plug-in under cn=plugin,cn=subconfigsubentry.

The orclPluginConfig Object Class

A plug-in must have orclPluginConfig as one of its object classes. This is a structural object class, and its super class is top. Table 9-3 lists and describes its attributes.

Table 9-3  Plug-in Attribute Names and Values
Attribute Name Attribute Value Mandatory Optional

Cn

Plug-in entry name

X

-

orclPluginName

Plug-in package name

X

-

orclPluginType

One of the following values:

operational
attribute
password_policy
syntax
matchingrule

See Also: Operation-Based Plug-ins Supported in Oracle Internet Directory

X

-

orclPluginKind

PL/SQL

-

X

orclPluginEnable

0 = disable (default)

1 = enable

-

X

orclPluginVersion

Supported plug-in version number

-

X

orclPluginShareLibLocation

File location of the dynamic linking library. If this value is not present, then Oracle Internet Directory server assumes the plug-in language is PL/SQL.

-

X

orclPluginLDAPOperation

One of the following values:

ldapcompare
ldapmodify
ldapbind
ldapadd
ldapdelete
ldapsearch

-

X

orclPluginTiming

One of the following values:

pre
when
post

-

X

orclPluginIsReplace

0 = disable (default)

1 = enable

For WHEN timing plug-in only

-

X

orclPluginSubscriberDNList

A semicolon separated DN list that controls if the plug-in takes effect. If the target DN of an LDAP operation is included in the list, then the plug-in is invoked.

-

X

Adding a Plug-in Configuration Entry by Using Command-Line Tools

Plug-ins must be added to Oracle Internet Directory server so that the server is aware of additional operations that must be performed at the correct time.

When the plug-in successfully compiles against the Oracle Internet Directory backend database, create a new entry and place it under cn=plugin,cn=subconfigsubentry.

In the following examples, an entry is created for an operation-based plug-in called my_plugin1. The LDIF file, my_ldif_file.ldif, is as follows:

Example 1

The following is an example LDIF file to create such an object:

cn=when_comp,cn=plugin,cn=subconfigsubentry
objectclass=orclPluginConfig
objectclass=top
orclPluginName=my_plugin1
orclPluginType=operational
orclPluginTiming=when
orclPluginLDAPOperation=ldapcompare
orclPluginEnable=1
orclPluginVersion=1.0.1
orclPluginIsReplace=1
cn=when_comp
orclPluginKind=PLSQL
orclPluginSubscriberDNList=dc=COM,c=us;dc=us,dc=oracle,dc=com;dc=org,dc=us;o=IMC
,c=US

Example 2

cn=post_mod_plugin, cn=plugin,cn=subconfigsubentry
objectclass=orclPluginConfig
objectclass=top
orclPluginName=my_plugin1
orclPluginType=operational
orclPluginTiming=post
orclPluginLDAPOperation=ldapmodify
orclPluginEnable=1
orclPluginVersion=1.0.1
cn=post_mod_plugin
orclPluginKind=PLSQL

Add this file to the directory with the following command:

ldapadd -p 389 -h myhost -D binddn -w password -f my_ldif_file.ldif

When you have added this entry to the directory, the directory server validates the plug-in by quickly executing it and checking for compilation or access privilege errors. It then gathers more information about this plug-in--such as timing and the type of LDAP operation related to the plug-in.


Notes:

The plug-in configuration entry, for example, cn=plugin,cn=subconfigsubentry metadata is not replicated in the replication environment to avoid creating inconsistent state.


Managing Plug-ins

This section explains modifying plug-ins and debugging plug-ins.

Modifying Plug-ins

Similar to a stored procedure, a plug-in cannot be explicitly altered. It must be replaced with a new definition.

When replacing a plug-in, you must include the OR REPLACE option in the CREATE PACKAGE statement. The OR REPLACE option enables a new version of an existing plug-in to replace an older version without having an effect on grants made for the original version of the plug-in.

Alternatively, the plug-in can be dropped using the DROP PACKAGE statement, and you can rerun the CREATE PACKAGE statement.

If the plug-in name (the package name) is changed, then you must register the new plug-in again.

Debugging Plug-ins

You can debug a plug-in using the same facilities available for stored procedures.

Enabling and Disabling Plug-ins

To turn the plug-in on/off, modify the value of orclPluginEnable in the plug-in configuration object. For example, modify the value of orclPluginEnable in cn=post_mod_plugin, cn=plugins,cn=subconfigsubentry to be 1/0. You must restart the Oracle Internet Directory server after you modify the orclPluginEnable value.

Exception Handling

In each of the plug-in PL/SQL procedures, there must be an exception handling block to handle errors intelligently and recover from them, if possible.

See Also:

PL/SQL Programming, Error Handling manual for information about how to use exceptions in a PL/SQL programming block

Error Handling

Oracle Internet Directory requires that the return code (rc) and error message (errmsg) are set correctly in the plug-in procedures.

The valid values for the return code is as follows:

Error Code Description

0

Success

Any number greater than zero (0)

Failure, See Also LDAP Server Error Code Reference

-1

Warning

The errmsg parameter is a string value that can pass a user's custom error message back to Oracle Internet Directory server. The size limit for errmsg is 1024 bytes. Each time Oracle Internet Directory runs the plug-in program, following the run, Oracle Internet Directory examines the return code to determine if it must display the error message.

For example, if the value for the return code is 0, then the error message value is ignored. If the value of the return code is -1 or greater than zero, then the following message is either logged in the log file or displayed on the standard output if the request came from LDAP command-line tools:

ldap addition info: customized error 

Program Control Handling between Oracle Internet Directory and Plug-ins

When a plug-in exception is occurring, the following describes where the plug-in exception occurred and the Oracle Internet Directory server handling of the exception.

Table 9-4  Program Control Handling when a Plug-in Exception Occurs
Plug-in Exception Occurred in Oracle Internet Directory Server Handling

PRE_BIND, PRE_MODIFY, PRE_ADD, PRE_SEARCH, PRE_COMPARE, PRE_DELETE

Depends on return code. If the return code is:

Greater than zero (error), then no LDAP operation is performed

-1 (warning), then proceed with the LDAP operation

POST_BIND, POST_MODIFY, POST_ADD, POST_SEARCH, WHEN_COMPARE, WHEN_DELETE

LDAP operation is completed. There is no rollback.

WHEN_BIND, WHEN_MODIFY, WHEN_ADD, WHEN_SEARCH, WHEN_COMPARE, WHEN_DELETE

Rollback the LDAP operation

When an LDAP operation fails, the following describes the target and the Oracle Internet Directory server handling of the failure.

Table 9-5  Program Control Handling when an LDAP Operation Fails
LDAP Operation Fails in Oracle Internet Directory Server Handling

PRE_BIND, PRE_MODIFY, PRE_ADD, PRE_SEARCH, WHEN_COMPARE, WHEN_DELETE

Pre-operation plug-in is completed. There is no rollback.

POST_BIND, POST_MODIFY, POST_ADD, POST_SEARCH, WHEN_COMPARE, WHEN_DELETE

Proceed with post-operation plug-in. The LDAP operation result is one of the IN parameters.

WHEN_BIND, WHEN_MODIFY, WHEN_ADD, WHEN_SEARCH, WHEN_COMPARE, WHEN_DELETE

When types of plug-in changes are rolled back.

WHEN Replacement

Changes made in the plug-in program body are rolled back.

Plug-in LDAP API

There are different methods for providing API access as follows:

In the Plug-in LDAP API, Oracle Internet Directory provides APIs for connecting back to the same Oracle Internet Directory server within the plug-in module. In other words, within the plug-in module, if you want to connect to any external LDAP server, you can use the DBMS_LDAP API. If you want to connect to the same Oracle Internet Directory server that is executing this plug-in itself, then you must use the Plug-in LDAP API for binding and authentication.

Within each plug-in module, there is a ldapcontext passed from Oracle Internet Directory server. When we call the Plug-in LDAP API, we must pass this ldapcontext for security and binding purposes. When binding with this ldapcontext, Oracle Internet Directory server recognizes this LDAP request is coming from a plug-in module. For this type of plug-in bind, Oracle Internet Directory server does not trigger any subsequent plug-ins, and Oracle Internet Directory server handles this kind of plug-in bind as a super-user bind. Use this plug-in bind with discretion.

See Also:

Plug-in LDAP API Specifications for coding examples

Plug-in and Replication

There are cases that can cause an inconsistent state in a replication environment as follows:

Plug-in and DB Tools

Bulk tools do not support server plug-ins.

Security

Some Oracle Internet Directory server plug-ins require you to supply the code that preserves tight security. For example, if you replace Oracle Internet Directory's ldapcompare or ldapbind operation with your own plug-in module, you must ensure that your implementation of this operation does not omit any functionality on which security relies.

To ensure tight security, the following must be done:

Plug-in LDAP API Specifications

CREATE OR REPLACE  PACKAGE LDAP_PLUGIN AS
    SUBTYPE SESSION IS RAW(32);
    -- Initializes the LDAP library and return a session handler
    -- for use in subsequent calls.
    FUNCTION init (ldappluginctx IN ODS.plugincontext)
      RETURN SESSION;
    -- Synchronously authenticates to the directory server using
    -- a Distinguished Name and password.
    FUNCTION simple_bind_s (ldappluginctx IN ODS.plugincontext,
                            ld            IN SESSION)
      RETURN PLS_INTEGER;
END LDAP_PLUGIN;

Usage Model and Examples

This section contains two example situations about search query logging and synchronizing two directory information trees (DITs).

Example 1: Search Query Logging

Situation: A user wants to know if it is possible to log all the ldapsearch commands.

Solution: Yes. Using the POST ldapsearch operational plug-in then the user can log all the ldapsearch commands. They can either log all the ldapsearch requests, or log all the ldapsearch requests if the search occurs under certain DNs (under a specific subtree).

To log all the ldapsearch commands, do the following:

  1. Preparation.

    Log all of the ldapsearch results into a database table. This log table will have the following columns:

    • timestamp
    • baseDN
    • search scope
    • search filter
    • required attribute
    • search result

    Use the following SQL script to create the table:

    drop table search_log;
    create table search_log 
    
    (timestamp varchar2(50),
    basedn varchar2(256),
    searchscope number(1);
    searchfilter varchar2(256);
    searchresult number(1));
    
    drop table simple_tab;
    create table simple_tab (id NUMBER(7), dump varchar2(256));
    DROP sequence seq;
    CREATE sequence seq START WITH 10000;
    commit;
    
    
  2. Create the plug-in package specification.
    CREATE OR REPLACE PACKAGE LDAP_PLUGIN_EXAMPLE1 AS
    PROCEDURE post_search 
    
    (ldapplugincontext IN  ODS.plugincontext,
    result       IN  INTEGER,
    baseDN       IN  VARCHAR2,
    scope        IN  INTEGER,
    filterStr    IN  VARCHAR2,
    requiredAttr IN  ODS.strCollection,
    rc           OUT INTEGER,
    errormsg     OUT VARCHAR2
    );
    
    END LDAP_PLUGIN_EXAMPLE1;
    /
    
  3. Create plug-in package body.
    CREATE OR REPLACE PACKAGE BODY LDAP_PLUGIN_EXAMPLE1 AS
    PROCEDURE post_search 
    
    (ldapplugincontext IN  ODS.plugincontext,
    result       IN  INTEGER,
    baseDN       IN  VARCHAR2,
    scope        IN  INTEGER,
    filterStr    IN  VARCHAR2,
    requiredAttr IN  ODS.strCollection,
    rc           OUT INTEGER,
    errormsg     OUT VARCHAR2
    )
    
          IS
    BEGIN
       INSERT INTO simple_tab VALUES 
    
    (to_char(sysdate, 'Month DD, YYYY HH24:MI:SS'), baseDN, scope, 
    filterStr, result);
    
       -- The following code segment demonstrate how to iterate
       -- the ODS.strCollection 
       FOR l_counter1 IN 1..requiredAttr.COUNT LOOP
          INSERT INTO simple_tab
            values (seq.NEXTVAL, 'req attr ' || l_counter1 || ' = ' ||
                    requiredAttr(l_counter1));
       END LOOP;
       rc := 0;
       errormsg := 'no post_search plguin error msg';
       COMMIT;
    EXCEPTION
       WHEN others THEN
          rc := 1;
          errormsg := 'exception: post_search plguin';
    END;
    END LDAP_PLUGIN_EXAMPLE1;
    /
    
    
  4. Grant permission to ods_server.
    GRANT EXECUTE ON LDAP_PLUGIN_EXAMPLE1 TO ods_server;
    
    
  5. Register plug-in entry to Oracle Internet Directory server.

    Use the following to construct an LDIF file (register_post_search.ldif):

    cn=post_search,cn=plugin,cn=subconfigsubentry
    objectclass=orclPluginConfig
    objectclass=top
    orclPluginName=ldap_plugin_example1
    orclPluginType=operational
    orclPluginTiming=post
    orclPluginLDAPOperation=ldapsearch
    orclPluginEnable=1
    orclPluginVersion=1.0.1
    cn=post_search
    orclPluginKind=PLSQL
    
    

    Using the ldapadd command-line tool to add this entry:

    % ldapadd -p port_number -h host_name -D bind_dn -w passwd -v -f register_
    post_search.ldif
    
    
  6. Restart the Oracle Internet Directory server

Example 2: Synchronizing Two DITs

Situation: There are two dependent products under cn=Products, cn=oraclecontext where the users in these products have a one-to-one relationship in Oracle Internet Directory. If a user in the first DIT (product 1) is deleted, we want to delete the corresponding user in the other DIT (product 2) since a a relationship exists between these users.

Is there a way to set a trigger within Oracle Internet Directory that, on the event of deleting the user in the first DIT, will call or pass a trigger to delete the user in the second DIT?

Solution: Yes, we can use the POST ldapdelete operation plug-in to handle the second deletion occurring in the second DIT.

If the first DIT has the naming context of cn=DIT1,cn=products,cn=oraclecontext and the second DIT has the naming context of cn=DIT2,cn=products,cn=oraclecontext, then the relationship between the two users in the different DITs is that they share the same ID attribute. Basically, inside of the post ldapdelete plug-in module, we use LDAP_PLUGIN and DBMS_LDAP APIs to delete the corresponding user in the 2nd DIT.

We must set orclPluginSubscriberDNList to cn=DIT1,cn=products,cn=oraclecontext, so that whenever we delete entries under cn=DIT1,cn=products,cn=oraclecontext, the plug-in module is invoked.

  1. Preparation.

    Assume the entries under both DITs have been added into the directory. For example, the entry id=12345,cn=DIT1,cn=products,cn=oraclecontext is in DIT1, and id=12345,cn=DIT2,cn=products,cn=oraclecontext is in DIT2.

  2. Create the plug-in package specification.
    CREATE OR REPLACE PACKAGE LDAP_PLUGIN_EXAMPLE2 AS
    PROCEDURE post_delete 
    
    (ldapplugincontext IN  ODS.plugincontext,
    result   IN  INTEGER,
    dn       IN  VARCHAR2,
    rc       OUT INTEGER,
    errormsg OUT VARCHAR2
    ); 
    
    END LDAP_PLUGIN_EXAMPLE2;
    /
    
    
  3. Create plug-in package body.
    CREATE OR REPLACE PACKAGE BODY LDAP_PLUGIN_EXAMPLE2 AS
    PROCEDURE post_delete 
    
    (ldapplugincontext IN  ODS.plugincontext,
    result   IN  INTEGER,
    dn       IN  VARCHAR2,
    rc       OUT INTEGER,
    errormsg OUT VARCHAR2
    )
    
        IS
         retval       PLS_INTEGER;
         my_session   DBMS_LDAP.session;
         newDN        VARCHAR2(256);
    BEGIN
       retval         := -1;
       my_session := LDAP_PLUGIN.init(ldapplugincontext);
       -- bind to the directory
       retval := LDAP_PLUGIN.simple_bind_s(ldapplugincontext, my_session);
       -- if retval is not 0, then raise exception
       newDN := REPLACE(dn, `DIT1', `DIT2');
       retval := DBMS_LDAP.delete_s(my_session, newDN);
       -- if retval is not 0, then raise exception
       rc := 0;
       errormsg := 'no post_delete plguin error msg';
    EXCEPTION
       WHEN others THEN
          rc := 1;
          errormsg := 'exception: post_delete plguin';
    END; 
    END LDAP_PLUGIN_EXAMPLE2;
    /
    
    
  4. Register plug-in entry to Oracle Internet Directory server.

    Use the following to construct a LDIF file (register_post_delete.ldif):

    cn=post_delete,cn=plugin,cn=subconfigsubentry
    objectclass=orclPluginConfig
    objectclass=top
    orclPluginName=ldap_plugin_example2
    orclPluginType=operational
    orclPluginTiming=post
    orclPluginLDAPOperation=ldapdelete
    orclPluginEnable=1
    orclPluginSubscriberDNList=cn=DIT1,cn=oraclecontext,cn=products
    orclPluginVersion=1.0.1
    cn=post_delete
    orclPluginKind=PLSQL
    
    

    Use the ldapadd command-line tool to add the following entry:

    % ldapadd -p port_number -h host_name -D bind_dn -w passwd -v -f register_
    post_delete.ldif
    
    
  5. Restart the Oracle Internet Directory server

Type Definition & Usage Model

This section gives examples of database object type definitions and LDAP_PLUGIN API Specifications.

This section contains these topics:

Database Object Type Definitions

This section contains the object definitions for those object types introduced in the Plug-in LDAP API. All these definitions are in Oracle Directory Server (ODS) database schema.

create or replace type strCollection as TABLE of VARCHAR2(512);
/

create or replace type pluginContext as TABLE of VARCHAR2(512);
/

create or replace type attrvalType as TABLE OF VARCHAR2(4000);
/
create or replace type attrobj as object (
attrname varchar2(2000),
attrval attrvalType
);
/

create or replace type attrlist as table of attrobj;
/

create or replace type entryobj as object (
entryname varchar2(2000),
attr      attrlist
);
/

create or replace type entrylist as table of entryobj;
/

create or replace type bvalobj as object (
length integer,
val    varchar2(4000)
);
/

create or replace type bvallist as table of bvalobj;
/

create or replace type modobj as object (
operation integer,
type      varchar2(256),
vals      bvallist
);
/

create or replace type modlist as table of modobj;
/

Plug-in Module Interface Specifications

You must follow the procedure signature to use ldapbind, ldapsearch, ldapdelete, ldapadd, ldapcompare, and ldapmodify plug-ins.

CREATE or replace PACKAGE plugin_test1 AS

PROCEDURE pre_add (ldapplugincontext IN  ODS.plugincontext,


dn       IN  VARCHAR2,
entry    IN  ODS.entryobj,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE when_add (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
entry    IN  ODS.entryobj,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE post_add (ldapplugincontext IN ODS.plugincontext,
result   IN  INTEGER,
dn       IN  VARCHAR2,
entry    IN  ODS.entryobj,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE pre_modify (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE when_modify (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE when_modify_replace (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE post_modify (ldapplugincontext IN ODS.plugincontext,
result   IN  INTEGER,
dn       IN  VARCHAR2,
mods     IN  ODS.modlist,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE pre_compare (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE when_compare (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE when_compare_replace (ldapplugincontext IN ODS.plugincontext,
result   OUT INTEGER,
dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE post_compare (ldapplugincontext IN ODS.plugincontext,
result   IN  INTEGER,
dn       IN  VARCHAR2,
attrname IN  VARCHAR2,
attrval  IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE pre_delete (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE when_delete (ldapplugincontext IN ODS.plugincontext,
dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE post_delete (ldapplugincontext IN ODS.plugincontext,
result   IN  INTEGER,
dn       IN  VARCHAR2,
rc       OUT INTEGER,
errormsg OUT VARCHAR2
);
PROCEDURE pre_search (ldapplugincontext IN ODS.plugincontext,
baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);
PROCEDURE when_search (ldapplugincontext IN ODS.plugincontext,
baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);
PROCEDURE post_search (ldapplugincontext IN ODS.plugincontext,
result       IN  INTEGER,
baseDN       IN  VARCHAR2,
scope        IN  INTEGER,
filterStr    IN  VARCHAR2,
requiredAttr IN  ODS.strCollection,
rc           OUT INTEGER,
errormsg     OUT VARCHAR2
);
PROCEDURE pre_bind (ldapplugincontext IN ODS.plugincontext,
dn IN VARCHAR2,
passwd IN VARCHAR2,
rc OUT INTEGER,
errormsg   OUT VARCHAR2
);

PROCEDURE when_bind (ldapplugincontext IN ODS.plugincontext,
dn IN VARCHAR2,
passwd IN VARCHAR2,
rc OUT INTEGER,
errormsg   OUT VARCHAR2
);

PROCEDURE post_bind (ldapplugincontext IN ODS.plugincontext,
result IN INTEGER,
dn IN VARCHAR2,
passwd IN VARCHAR2,
rc OUT INTEGER,
errormsg OUT VARCHAR2
);

END plugin_test1; /

LDAP Server Error Code Reference

  
--------------------------------------------------------------------------------      
---Package specification for DBMS_LDAP
---     This is the primary interface used by various clients to
---     make LDAP requests
------------------------------------------------------------------------
CREATE OR REPLACE PACKAGE DBMS_LDAP AS   
-- ...
     -- possible error codes we can return from LDAP server
     --
     SUCCESS                   CONSTANT NUMBER := 0;
     OPERATIONS_ERROR          CONSTANT NUMBER := 1;
     PROTOCOL_ERROR            CONSTANT NUMBER := 2;
     TIMELIMIT_EXCEEDED        CONSTANT NUMBER := 3;
     SIZELIMIT_EXCEEDED        CONSTANT NUMBER := 4;
     COMPARE_FALSE             CONSTANT NUMBER := 5;
     COMPARE_TRUE              CONSTANT NUMBER := 6;
     STRONG_AUTH_NOT_SUPPORTED CONSTANT NUMBER := 7;
     STRONG_AUTH_REQUIRED      CONSTANT NUMBER := 8;
     PARTIAL_RESULTS           CONSTANT NUMBER := 9;
     REFERRAL                  CONSTANT NUMBER := 10;
     ADMINLIMIT_EXCEEDED       CONSTANT NUMBER := 11;
     UNAVAILABLE_CRITIC        CONSTANT NUMBER := 12;
      NO_SUCH_ATTRIBUTE         CONSTANT NUMBER := 16;
     UNDEFINED_TYPE            CONSTANT NUMBER := 17;
     INAPPROPRIATE_MATCHING    CONSTANT NUMBER := 18;
     CONSTRAINT_VIOLATION      CONSTANT NUMBER := 19;
     TYPE_OR_VALUE_EXISTS      CONSTANT NUMBER := 20;
     INVALID_SYNTAX            CONSTANT NUMBER := 21;
     NO_SUCH_OBJECT            CONSTANT NUMBER := 32;
     ALIAS_PROBLEM             CONSTANT NUMBER := 33;
     INVALID_DN_SYNTAX         CONSTANT NUMBER := 34;
     IS_LEAF                   CONSTANT NUMBER := 35;
     ALIAS_DEREF_PROBLEM       CONSTANT NUMBER := 36;
     INAPPROPRIATE_AUTH        CONSTANT NUMBER := 48;
     INVALID_CREDENTIALS       CONSTANT NUMBER := 49;
     INSUFFICIENT_ACCESS       CONSTANT NUMBER := 50;
     BUSY                      CONSTANT NUMBER := 51;
     UNAVAILABLE               CONSTANT NUMBER := 52;
     UNWILLING_TO_PERFORM      CONSTANT NUMBER := 53;
     LOOP_DETECT               CONSTANT NUMBER := 54;
     NAMING_VIOLATION          CONSTANT NUMBER := 64;
     OBJECT_CLASS_VIOLATION    CONSTANT NUMBER := 65;
     NOT_ALLOWED_ON_NONLEAF    CONSTANT NUMBER := 66;
     NOT_ALLOWED_ON_RDN        CONSTANT NUMBER := 67;
     ALREADY_EXISTS            CONSTANT NUMBER := 68;
     NO_OBJECT_CLASS_MODS      CONSTANT NUMBER := 69;
     RESULTS_TOO_LARGE         CONSTANT NUMBER := 70;
     OTHER                     CONSTANT NUMBER := 80;
     SERVER_DOWN               CONSTANT NUMBER := 81;
     LOCAL_ERROR               CONSTANT NUMBER := 82;
     ENCODING_ERROR            CONSTANT NUMBER := 83;
     DECODING_ERROR            CONSTANT NUMBER := 84;
     TIMEOUT                   CONSTANT NUMBER := 85;
     AUTH_UNKNOWN              CONSTANT NUMBER := 86;
     FILTER_ERROR              CONSTANT NUMBER := 87;
     USER_CANCELLED            CONSTANT NUMBER := 88;
     PARAM_ERROR               CONSTANT NUMBER := 89;
     NO_MEMORY                 CONSTANT NUMBER := 90;
 }

Go to previous page Go to next page
Oracle
Copyright © 1999, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback