Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Implementing a Solution
After determining the purpose and considering design issues, implement your solution. As mentioned earlier, the main components of a solution are as follows:
Client application
Parser
Extended operation
Pre- and post-operation plug-ins
For our example, we write the client application in Java, using the JavaTM Netscape API for the Sun Java System Directory Server. The following is a code excerpt for our client example:
CODE EXAMPLE 4 Client Application Sample
...
try
{
ld = new LDAPConnection();
// some basic setup and info
miscellaneus(ld);
// connect to the server
System.out.println("Connecting to \'" + host + ":" + port +"\'");
ld.connect( host, port );
// binds as with admin credentials
// Remember to specify LDAPv3,
// otherwise you will not be able
// to use extended operatins
System.out.println("Binding as \'" + binddn +"\'");
ld.bind(3, binddn, bindpw);
// in loop for user input
String data = getUserInput();
byte[] databytes = data.getBytes("UTF8");
// prepare the extended operation object
LDAPExtendedOperation extop = new
LDAPExtendedOperation(extopOID, databytes);
// invoke the server extended operation
System.out.println("Calling extended operation " + extopOID);
LDAPExtendedOperation extres = ld.extendedOperation(extop);
// get results
String id = extres.getID();
String response = new String(extres.getValue(), "UTF8");
System.out.println("Returned OID: " + id);
System.out.println("Returned Data: " + response);
// disconnect
ld.disconnect();
}
...
When started, the program shows the TRIGGERS>> prompt and waits for your statements. To execute the program, use the makefile run target, which sets up the classpath for you and runs the main Java class:
CODE EXAMPLE 5 Executing the Program
<nico client>~$ make run /usr/java/bin/java -cp /opt/sunone/ldapjdk41/packages/ldapjdk.jar:$CLASSPATH TriggersClient Proprietary protocol: 3.0 LDAP SDK: 4.1 Logging LDAP activity on file +error.log Connecting to 'localhost:10389' Binding as "cd=Trigger Manager" Triggers Client Insert your commands, a line with '.' terminates input triggers>>
NOTE
The application manages triggers in Sun Java System Directory Server using the account cn=Trigger Manager. Create this in the server, and grant it all permissions for the ou=triggers, o=sunblueprints branch.
To terminate a command list, type a line with just a ".", as shown in the following example:
CODE EXAMPLE 6 Terminating a Command List
... TRIGGERS>> create or replace trigger BeHappyWithSunBlueprints on 'o=sunblueprints' before ldap_add action ignore; disable trigger myspecialtrg; ! cat /etc/hosts \; . ...
The example shows a special feature of our language: the ! escape feature. Issuing a command escape by using a ! results in the execution of a UNIX command on the server. In this case, you would see the host database of the LDAP server machine on your client terminal.
After the ".", the program runs the extended operation, turns the resulted data into UTF8 representation, and displays it to the user on the terminal.
The UNIX command is just one possibility of our language. The grammar of the trigger language is partially shown in the following example:
CODE EXAMPLE 7 Trigger Language Grammar
cmdlist:
cmd ';'
|
cmdlist cmd ';'
;
cmd:
trgcmd
|
cntlcmd
|
unixcmd
;
trgcmd:
CREATE OR REPLACE TRIGGER STRING ON what BEFORE operation ACTION action
{
CURRENT_STATEMENT.cmdcode = TRIGGER_CREATE;
strcpy(CURRENT_STATEMENT.name, $5);
strcpy(CURRENT_STATEMENT.what, $7);
strcpy(CURRENT_STATEMENT.operation, $9);
CURRENT_STATEMENT.before = 1;
sprintf($$, "%s %s %s %s %s %s %s %s %s %s",
$1, $2, $3, $4, $5, $6, $7, $9, $10, $11);
}
|
CREATE OR REPLACE TRIGGER STRING ON what AFTER operation ACTION action
{
CURRENT_STATEMENT.cmdcode = TRIGGER_CREATE;
strcpy(CURRENT_STATEMENT.name, $5);
strcpy(CURRENT_STATEMENT.what, $7);
strcpy(CURRENT_STATEMENT.operation, $9);
CURRENT_STATEMENT.before = 0;
sprintf($$, "%s %s %s %s %s %s %s %s %s %s",
$1, $2, $3, $4, $5, $6, $7, $9, $10, $11);
}
|
ENABLE TRIGGER STRING
|
DISABLE TRIGGER STRING
|
DELETE TRIGGER STRING
|
LIST ALL TRIGGERS
|
EXPLAIN TRIGGER STRING
;
what:
'"' QSTRING '"'
|
ANY ENTRY
;
operation:
LDAP_ADD
|
LDAP_DELETE
|
LDAP_MODIFY
|
LDAP_MODRDN
|
LDAP_BIND
|
LDAP_UNBIND
|
LDAP_ABANDON
;
action:
DELETE '"' QSTRING '"'
|
DELETE '"' QSTRING '"' ON ERROR CONTINUE
|
LOG
|
IGNORE
|
EXECUTE EXTERNAL LIB STRING
|
EXECUTE EXTERNAL LIB STRING ON ERROR CONTINUE
;
cntlcmd:
SET STRING '=' STRING
|
SET STRING '=' NUMERIC
|
GET STRING
;
unixcmd:
'!' STRING
|
'!' STRING cmdargs
;
cmdargs:
STRING
|
cmdargs STRING
;
%%
NOTE
For clarity, the grammar in this code example does not show all actions.
Our language is a list of statements separated by semicolons ";". Then, each command can be one of the following:
A standard trigger command (for example, CREATE OR REPLACE TRIGGER)
A control command (for example, to set the environment with SET var=name)
A UNIX command (a command with "!" escape symbol)
The rest of the grammar defines commands and other syntactical components. If you are interested in complete details, the grammar is in the triggers.y file.
The LEXer specification file tells LEX how to extract tokens from the source text; the specification file is triggers.l.
NOTE
Unfortunately YACC and LEX are not designed for a concurrent environment.
Another limitation is that LEX expects its input to come from yyin global variable, which is a FILE * object; however, our input is a string passed by the client application, and we are forced to create a temporary file, write in the text, and assign the handler to the yyin global variable. A way to work around this is to define your own input() routine, which LEX uses in place of its default. However, this extension mechanism greatly depends on the version of LEX. If you want to remove any nonre-entrant problem from your code, use one of the latest versions of LEX, which have been redesigned.
NOTE
The code in {} parenthesis represents the C code that we want the parser to execute after a command or statement is read.
The extended operation is responsible for the following tasks:
Retrieving its argument
Passing it to the parser
Getting the parser output
Calling a coded function for any of the parsed statements
The following code shows how trg_service_fn, the extended operation routine, works:
CODE EXAMPLE 8 How trg_service_fn Works
int trg_service_fn(Slapi_PBlock *pb)
{
char * oid = NULL; /* Client request OID */
struct berval * client_bval = NULL; /* Value from client */
char * result = NULL; /* Result to send to client */
struct berval * result_bval = NULL; /* Encoded result */
int rc = 0;
int i;
int len;
ParsedStatements stmts; /* Result of the parsing */
char msgbuf[MAX_MSGBUF];
/* log */
log_info_conn(pb,
"trg_service_fn",
"Entering pb=%p", pb);
/* Get the OID and the value included in the request.
* The client_bval will contain the sequence of statements
* submitted by the client
*/
log_info_conn(pb,
"trg_service_fn",
"Getting ext opt request data...");
rc |= slapi_pblock_get(pb, SLAPI_EXT_OP_REQ_OID, &oid );
rc |= slapi_pblock_get(pb, SLAPI_EXT_OP_REQ_VALUE, &client_bval);
if (rc != 0)
{
snprintf(msgbuf,
MAX_MSGBUF,
"Unable to get client OID/Value data: %d",
rc);
goto TRIGGERS_ERROR;
}
log_info_conn(
pb,
"trg_service_fn",
"Request with OID: %s Value from client: %s\n",
oid, client_bval->bv_val);
/* Parsing the client statements
* We invoke a separate routine to parse the client
* statements.
* The statements are stored in the stms structure */
stmts.statements = 0;
rc = trg_parse_client_req(pb, client_bval, &stmts);
if(rc != OK)
{
snprintf(msgbuf,
MAX_MSGBUF,
"trg_parse_client_req failed(%d)",
rc);
goto TRIGGERS_ERROR;
}
/* Is at this point, parsing was successful.
* Now we invoke the routine that creates triggers
* as LDAP objects
*/
rc = trg_apply_statements(pb, &stmts, &result_bval);
if(rc != OK)
{
snprintf(msgbuf,
MAX_MSGBUF,
"trg_apply_statements failed(%d)",
rc);
goto TRIGGERS_ERROR;
}
/* Calculate the amount of text data
* to be returned to the client */
for(i = 0, len = 0; i < stmts.statements; ++i)
{
len += sprintf(msgbuf, "Statement #%d\n", i) - 1;
len += strlen("Error code: ");
len += sprintf(msgbuf, "%d\n", i) - 1;
len += strlen("Error msg: ");
len += strlen(stmts.opres[i].errmsg);
len += 1; /* \n */
len += strlen(stmts.opres[i].out);
len += 1; /* \n */
len += 1; /* \n */
}
/*
* Set the value to return to the client, depending on what your
* plug-in function does. Here, we return the value sent by the
* client, prefixed with the string "Value from client: ". */
result = (char *)slapi_ch_malloc(len + 1);
for(i = 0, result[0] = '\0'; i < stmts.statements; ++i)
{
sprintf(msgbuf, "Statement #%d\n", i);
strcat(result, "Error code: ");
sprintf(msgbuf, "%d\n", i);
strcat(result, msgbuf);
strcat(result, "Error msg: ");
strcat(result, stmts.opres[i].errmsg);
strcat(result, "\n");
strcat(result, stmts.opres[i].out);
strcat(result, "\n");
}
log_info_conn(pb,
"trg_service_fn",
"Client statements executed");
result_bval = (struct berval *)slapi_ch_malloc(
sizeof(struct berval));
result_bval->bv_val = result;
result_bval->bv_len = strlen(result_bval->bv_val) + 1;
/* Prepare the PBlock to return and OID and value to the client.
* Here, we demonstrate that the plug-in may return a different
* OID than the one sent by the client. You may, for example,
* use the different OID to indicate something to the client. */
rc |= slapi_pblock_set(pb, SLAPI_EXT_OP_RET_OID, "4.3.2.1");
rc = slapi_pblock_set(pb, SLAPI_EXT_OP_RET_VALUE, result_bval);
if (rc != 0)
{
snprintf(msgbuf,
MAX_MSGBUF,
"Unable to set extended operation result value: %p",
result_bval);
goto TRIGGERS_ERROR;
}
/* Log data sent to the client */
log_info_conn(
pb,
"trg_service_fn",
"OID sent to client: %s \nValue sent to client:\n%s",
"", result);
/* Send the result back to the client */
slapi_send_ldap_result(
pb,
LDAP_SUCCESS,
NULL,
result,
0,
NULL);
/* Rree memory allocated for return berval */
if(result) slapi_ch_free_string(&result);
if(result_bval) slapi_ch_free((void **)&result_bval);
goto TRIGGERS_OK;
TRIGGERS_ERROR:
log_error_conn(pb,
0,
"trg_service_fn",
"Routing failed ",
msgbuf);
/* Sends back an error-result */
slapi_send_ldap_result(
pb,
LDAP_OPERATIONS_ERROR,
NULL,
msgbuf,
0,
NULL);
/* Free memory allocated for return berval */
if(result) slapi_ch_free_string(&result);
if(result_bval) slapi_ch_free((void **)&result_bval);
/* Tell the server that the operation completed */
return (SLAPI_PLUGIN_EXTENDED_SENT_RESULT);
TRIGGERS_OK:
/* Tell the server we've sent the result */
return (SLAPI_PLUGIN_EXTENDED_SENT_RESULT); /* ok! */
}
This example is a lot of code, however, apart from the logging and error management code, the logical flow is the following:
Take the extended operation value – This value contains the user statements, as typed on the client side).
Prepare and invoke the parser through the trg_parse_client_req routine – This routine parses the user commands, and for any command found, fills a structure in the ParsedStatements array passed from trg_service_fn.
Call the routine trg_apply_statements to apply statements – We have the binary representation of the user commands in a ParsedStatements structure, then invoke the routine trg_apply_statements to update the directory.
Prepare the result data for the client – The data has the form of sequential file with records of the following form:
CODE EXAMPLE 9 Sequential File Records Sample
Statement: 1 Error code: 0 Error msg: "OK!" <some output> Statement: 2 Error code: 1 Error message: Trigger already exists <some output> ...
Send the results back to the client.
Free resources.
Notice how we reply back to the client that invoked the extended operation. This reply is in fact a three-part operation:
Set the PBlock using the SLAPI_EXT_OP_RET_OID and SLAPI_EXT_OP_RET_VALUE (we could return an extend operation OID different from the client.)
Invoke the usual slapi_send_ldap_result(), which sends the result to the client.
Tell the server that we are done, returning SLAPI_PLUGIN_EXTENDED_SENT_RESULT.
The first routine invoked is trg_parse_client_req and contains the code that instantiates and runs the parser through the yyparse() routine, which is generated by YACC as part of the project's building.
The code is a bit tricky because of the nonre-entrant code generated by YACC: we are forced to use a lock (mutex) and generate a temporary file. The file pointer is then passed via the global variable yyin. The goal of trg_parse_client_req is to either fill a ParsedStatements structure with statements sent by the client or to return an appropriate error if the parser fails. For production, consider embedding a re-entrant parser in your extended operation plug-in; this approach is more suitable for a concurrent environment.
The other helper function is the trg_apply_statements routine. By itself, trg_apply_statements does not contain much logic, it simply runs a list of statement structures and switches on the value of the operation code associated with the statement. Based on this code, a routine is called to do the last job, which is recording the trigger in LDAP.
The following shows an example of trg_execute_create, which creates a trigger in the server:
CODE EXAMPLE 10 Creating a Trigger in the Server
static int trg_execute_create(Slapi_PBlock *pb, int index, ParsedStatements *stmts)
{
int rc;
...
char *base = "ou=triggers,o=sunblueprints";
char msgbuf[MAX_MSGBUF];
Slapi_DN *sdn = NULL;
Slapi_Entry *entry = NULL;
Slapi_PBlock *pbop = NULL;
char *entrydn = NULL;
char *entryldif = NULL;
int len;
if(!stmts || index < 0 )
return ERR;
name = stmts->output[index].name;
on = stmts->output[index].what;
before = stmts->output[index].before;
action = stmts->output[index].action;
action_dn = stmts->output[index].action_dn;
external_lib = stmts->output[index].external_lib;
if(!name || !on ) return ERR;
/* Make a SDN of the string dn */
sdn = slapi_sdn_new_dn_byval(base);
if(sdn == NULL)
{
snprintf(msgbuf,
MAX_MSGBUF,
"Unable to create a SDN from the string %s",
base);
goto CREATE_ERR;
}
...
/* prepare the entry to be added
* using data provided by user */
entrydn = slapi_ch_malloc(
+ strlen("cn=")
+ strlen(name)
+ 1
+ strlen(base)
+ 1);
sprintf(entrydn, "cn=%s,%s", name, base);
entry = slapi_entry_alloc();
slapi_entry_set_dn(entry, strdup(entrydn));
/* Set entry attributes. Note that slapi_entry_add_string
* does not consumes the string passed as parameter,
* hence we do not need a slapi_ch_strdup call */
slapi_entry_add_string(entry, "objectclass", "trigger");
slapi_entry_add_string(entry, "cn", name);
slapi_entry_add_string(entry, "on", on);
slapi_entry_add_string(entry, "before", before ? "1" : "0");
slapi_entry_add_string(entry, "enabled", "true");
snprintf(msgbuf, MAX_MSGBUF, "%d", action);
slapi_entry_add_string(entry, "action", msgbuf);
slapi_entry_add_string(entry, "actiondn", action_dn);
/* Preparing PBlock for internal add
* The plugin_id parameter was obtained
* int the _init function */
pbop = slapi_pblock_new();
slapi_add_entry_internal_set_pb(
pbop,
entry,
NULL,
plugin_id,
SLAPI_OP_FLAG_NEVER_CHAIN);
/* capture the entry's LDIF rapresentation
* before the internal add, which consumes the entry */
entryldif = slapi_entry2str(entry, &len);
/* Perform the internal add: which consists
* of calling slapi_add_internal_pb and getting
* the operation result from the slapi_pblock_get */
log_info_conn(
pb,
"trg_execute_create",
"Adding the entry ..." );
rc = slapi_add_internal_pb(pbop);
slapi_pblock_get(pbop, SLAPI_PLUGIN_INTOP_RESULT, &rc);
if(rc)
{
snprintf(msgbuf,
MAX_MSGBUF,
"slapi_pblock_get reported an error(%d) for the previous internal op",
rc);
goto CREATE_ERR;
}
log_info_conn(
pb,
"trg_execute_create",
"Created entry:\n %s",
entryldif);
/* Setting return data */
stmts->opres[index].errcode = 0;
snprintf( stmts->opres[index].errmsg,
MAX_ERR_MSG,
"Trigger %s successfully added",
stmts->output[index].name) ;
stmts->opres[index].out[0] = '\0';
/* Freeing some allocated memory
* and jumping to the ok label */
if(sdn) slapi_sdn_free(&sdn);
if(pbop) slapi_pblock_destroy(pbop);
goto CREATE_OK;
...
As we said previously, the trigger is executed before/after a standard LDAP operation, and it is the responsibility of our pre- and post-operation plug-in to understand whether a trigger must be activated for an operation on an LDAP entry.
To fulfill this goal, pre- and post-operation plug-ins during initialization need to register all pre- and post-operation functions.
CODE EXAMPLE 11 Registering Extended Operation Functions
...
/* Register postoperation routines
* We override all LDAP Operations */
rc = slapi_pblock_set(pb, SLAPI_PLUGIN_PRE_ADD_FN,
(void *)triggers_pre_add_fn);
rc |= slapi_pblock_set(pb, SLAPI_PLUGIN_PRE_MODIFY_FN,
(void *)triggers_pre_modify_fn);
rc |= slapi_pblock_set(pb, SLAPI_PLUGIN_PRE_DELETE_FN,
(void *)triggers_pre_delete_fn);
...
rc |= slapi_pblock_set(pb, SLAPI_PLUGIN_POST_ABANDON_FN,
(void *)triggers_post_abandon_fn);
rc |= slapi_pblock_set(pb, SLAPI_PLUGIN_POST_BIND_FN,
(void *)triggers_post_bind_fn);
rc |= slapi_pblock_set(pb, SLAPI_PLUGIN_POST_UNBIND_FN,
(void *)triggers_post_unbind_fn);
...
The registrations of pre- and post-operation functions are placed in two different routines: triggers_postop_init and triggers_pre_init. This action is necessary so that we can register two plug-ins: a pre-operation plug-in and a post-operation plug-in, even though the code is in a single source file and the shared object is the same.
When a pre-operation function like triggers_pre_add_fn gets called because of a user LDAP add operation, it calls a helper function called find_trigger_by_targetdn(), which searches for a trigger associated with the DN of the entry that the user is trying to add. If there is such a trigger, the routine executes the action defined by the trigger. The following is an excerpt of the code.
CODE EXAMPLE 12 Using Helper Functions
...
if(!find_trigger_by_targetdn(pb, &cb_data, dn, BEFORE_TRIGGER)
&& cb_data.nentries > 0)
{
/* STEP 2.1. Take the action associated
* to this trigger */
switch(cb_data.tr.action)
{
case ACTION_DELETE_DN:
/* Deleate some entry logically associated
* with entry being removed */
/* LEFT TO BE DONE AS AN EXERCISE */
break;
case ACTION_LOG:
/* Get added entry from the operational block */
rc = slapi_pblock_get(pb, SLAPI_ADD_ENTRY, &entry);
if(rc != 0)
{
sprintf(msgbuf,
"slapi_pblock_get(SLAPI_ADD_ENTRY,..)=%d",
rc);
err = rc;
goto PRE_ADD_ERR;
}
/* Get LDIF representation of the added entry */
ldif = slapi_entry2str(entry, &len);
log_info_conn(pb,
"TRIGGERED ACTION",
"THE FOLLOWING ENTRY HAS BEEN ADDED:\n------ NEW ENTRY -----\n%s\n",
ldif);
break;
case ACTION_IGNORE:
sprintf(msgbuf, "Trigger %s forbids the creation of entry %s",
cb_data.tr.name,
dn);
slapi_send_ldap_result(
pb,
LDAP_OPERATIONS_ERROR,
NULL,
msgbuf,
0,
NULL );
return ERR;
break;
case ACTION_EXTERNAL:
/* Load an external library, and execute
* a named function inside it */
/* LEFT AS AN EXERCISE */
break;
default:
log_warning_conn(pb,
0,
"triggers_pre_add_fn",
"Unrecognized action",
"No action taken");
break;
};
}
...
To search the trigger under ou=triggers,o=sunblueprints, we use an internal search operation (not shown, but in find_trigger_by_targetdn).
A few actions are implemented in our example. In the panel you see, for example, the LOG action, which consists of writing the entry to be added in LDIF format in the error log file. Another more interesting action implemented is IGNORE, which allows you to skip the operation. What this means is that the entry is not added, and the user receives an error message such as "Trigger stopItTrigger forbids you to add this entry."
More advanced action can now be easily added; it is just a matter of adding code in this routine. The framework does the rest of the work for you.