| Description |

LdapProcessor is a processor for Cocoon that performs LDAP queries, translates the resultset into an XML fragment, and inserts the fragment in the original document.The Ldap Processor was written for a project where I work, and carried back over into the Cocoon project.

| Installation |

Check your cocoon.properties for this line and add it if it's not already there:

    processor.type.ldap = org.apache.cocoon.processor.ldap.LdapProcessor

| Configuration |

Add this PI to the XML files to which you wish to add LDAP queries:

    <?cocoon-process type="ldap"?>

You probably want this before any "xslt" processing directives. Then add LDAP connection information to your XML files. The tagset for LDAP server defitions looks like this:

    <ldap-defs>
     <ldap-server name=foo_server">
      <initializer>com.sun.jndi.ldap.LdapCtxFactory</initializer>
      <ldap-serverurl>ldap://ldap.weber.edu</ldap-serverurl>
     </ldap-server>
    </ldap-defs>

This tagset will be removed from the document after processing.

In addition to the ldap-server element, you can also have querydefs tags in your ldap-defs node. A ldap-defs node must have a unique name attribute. ldap-query tags (described below) may reference a querydefs tag in their defs attribute, which causes the ldap-query tag's attributes to default to the attributes of the querydefs tag. This is useful for setting commonly used groups of attributes. You may also specify a default querydefs. Here is an example:

    <querydefs name="standard" doc-element="options"
      row-element="option" server="foo"/>
    <query defs="standard"/>

is equivalent to

    <ldap-query doc-element="options" row-element="option" connection="foo"/>

You can also flag a querydefs node as the default for all query tags by setting the default attribute to yes. Note that ldap-query tags can always override the defaults.

| Usage |

Add LDAP queries to your XML files. The tagset looks like this:

    <ldap-query server="foo_server">
     sn=*Green*
    </ldap-query>

This will be replaced by a tagset that looks something like this:

    <ldapsearch>
     <searchresult ID="CN=DGREEN,OU=TBE,OU=AST,OU=ACAD,O=WSU">
      <telephonenumber>801-626-6821</telephonenumber>
      <facsimiletelephonenumber>801-626-6650</facsimiletelephonenumber>
      <title>PROFESSOR/TELECOMMUNICATIONS AND BUSINESS EDUCATION</title>
      <givenname>Diana</givenname>
      <sn>Green</sn>
      <l>B2 218</l>
      <ou>TELECOM & BUSINESS ED </ou>
      <mail>DGREEN@weber.edu</mail>
      <initials>J</initials>
      <cn>DGREEN</cn>
      <objectclass>newPilotPerson</objectclass>
      <objectclass>organizationalPerson</objectclass>
      <objectclass>person</objectclass>
      <objectclass>top</objectclass>
     </searchresult>
    </ldapsearch>

You can also have the LdapProcessor substitute values from the servlet request into your query. The syntax for that is:

    <ldap-query name="foo_server">
     sn=*{@name}*
    </ldap-query>

This is, of course, highly configurable by setting attributes of the query tag. A partial list of attributes is:

> - doc-element -
> The tag with which to wrap the whole shebang. Default is ldapresults. If an empty string is specified, e.g. doc-element="", the whole shebang will not be wrapped.
> - row-element -
> The tag with which to wrap each row. Default is searchresult. Same deal as with doc-element.
> - id-attribute -
> What is the name of the attribute that uniquely identifies the rows? Default is ID. This is, of course, meaningless if row-element is set to an empty string.
> - variable-left-delimiter -
> What string delimits variables in the query on the left side? Default is {@.
> - variable-right-delimiter -
> What string delimits variables in the query on the right side? Default is }.

| Error Handling |

In a perfect world, nothing would ever go wrong in your queries but this is not a perfect world. In our world, you can check for Exceptions in your stylesheets and present them to your users in a nice way. The tags used to render the error are configurable using attributes from the query tag. The attributes in question are:

> - error-element -
> The name of the error-element to create, default is error.
> - error-message-attribute -
> The name of the attribute of the error-element in which to put the Exception's message. Default is message.
> - error-message-element -
> The name of the child element of the error-element in which to put the Exception's message. The default is to not do so.
> - error-stacktrace-attribute -
> The name of the attribute of the error-element in which to put the Exception's stacktrace. The default is to not do so.
> - error-stacktrace-element -
> The name of the child element of the error-element in which to put the Exception's stacktrace. The default is to not do so.
> - error-message-text -
> The text to pass out as an error message instead of the Exception's own message. This is useful for displaying user friendly error messages. The default is to use the Exception's message.

So by default, when an Exception occurs, the processor generates this XML:

    <error message="The server is on fire."/>

| Notes and Disclaimers |

The LdapProcessor was written borrowing a lot of ideas and code form Donald Ball's SQLProcessor. Any similarity to his code is purely intended...:) Thanks to Donald for writing good, clean code, and being a good sport about me plagerizing in the name of ultimate 'code re-use'.

| Planned Features |

> - support for different context paramaters such as authtype, protocol, and principal.
> - the ability to retrieve binary objects such as certificates and images.
> - the ability to add different Contols such as a SortContorl for server side sorting.

Copyright © 1999-2001 The Apache Software Foundation. All Rights Reserved.