Ldap Tag Library Documentation

Simya LDAP Tag Library Reference

INTRODUCTION

Simya Ldap Tag Library is a collection of custom JSP 1.1 tags that simplifies LDAP operations using Java Naming and Directory Interface (JNDI).

PRECONDITIONS

Java version : Java 1.1 or higher.

Server : Servlet 2.2 and JSP 1.1 compatible servlet engine.

LDAP Access : Simya Ldap Tag Library uses Sun's JNDI API and LDAP implementation which It comes with JDK 1.2 and later. If you are using JDK1.1, you should download and install JNDI and LDAP distribution first ( http://java.sun.com/products/jndi ) .

INSTALLATION

Simply copy ldap-<version>-bin.zip to your server's war directory and rename it to <appname>.war, then it's ready to access sample jsp pages in http://yourhost/your-app/examples directory. In order to embed Simya Taglib facitities to your own applications, you should follow these steps :

Copy ldaptaglib.jar to your application's WEB-INF/lib directory
Copy ldaptaglib.tld to your application's WEB-INF/tlds directory.
In your WEB-INF/web.xml file, declare taglib and cache servlet. (You can copy from our web.xml and paste to yours.)

USING TAG LIBRARY

Ldap Tag Library at a glance

<ldap:property  name=".." value=".." />

<ldap:connect url="ldap://.." dn=".." password=".."

            ssl=".." referral=".." authtype="..">

    <ldap:query id=".." basedn=".." filter=".." limit="..">

        <ldap:getDN/>

        <ldap:getAttribute name=".." delimiter=".." index=".."

            default=".." mimeType=".." />

    </ldap:query>

    <ldap:add dn=".." id=".." >

        <ldap:addAttribute name=".." value=".."/>

    </ldap:add>

    <ldap:modify dn=".." id=".." >

        <ldap:modifyAttribute name=".." value=".." type=".."/>

    </ldap:modify>

    <ldap:delete dn=".." />

    <ldap:modifydn olddn=".." newdn=".." />

</ldap:connect>

Simya LDAP Tags Explanation:

Tag	property
Description	Stores jndi directory context environmental variables in page context. Usage of this tag is optional. Declared properties will be used by <ldap:connect> tag later. You may also prefer to declare the same properties as attribues of <ldap:connect> tag.
Attributes	name	Directory context environmental variable name. There are some useful predefined names as the follows; factory = Context.INITIAL_CONTEXT_FACTORY url = Context.PROVIDER_URL dn = Context.SECURITY_PRINCIPAL password = Context.SECURITY_CREDENTIALS ssl = Context.SECURITY_PROTOCOL referral = Context.REFERRAL authtype = Context.SECURITY_AUTHENTICATION
	value	Value of environmental variable.
example	`<ldap:property name="<%= Context.SECURITY_PRINCIPAL %>" value="uid=orhan,ou=people,o=simya.net" /`> is equvalent to `<ldap:property name="dn" value="uid=orhan,ou=people,o=simya.net" />`

Tag	connect
Description	Creates directory context according specified values by its own attributes or by property tags. Notice that add, delete, query, modify tags are inner tags of connect.
Attributes	url	URL of the ldap server. For example ; ldap://localhost:389
	dn	Distinguished name of the user who wants to authenticate.
	password	Password of the user. If it is not provided, user connects to ldap as anonymous
	ssl	Turns SSL on. Available options on\|off, default: off.
	referral	Tag library doesn't follow referrals as default. To turn it on use "follow" value. Available options ignore\|follow\|throw.
	authtype	Specify the authentication mechanism, default:simple. This attribute supports all mechanisms specified by JNDI theoretically. Tested mechanisms are none\|simple\|CRAM-MD5\|DIGEST-MD5.

Tag	query
Description	Searches the directory and starts a loop for entries.
Attributes	id	Name for scripting variable. See note for metods of binded object.
	basedn	It specifies the starting point of the search.
	filter	Ldap filter. For example "cn=orhan*".
	scope	scope of the query. The options are "base \| one \| sub". "base" indicates object base, "one" means one level below , "sub" covers all the tree.
	limit	Limit the number of returning entries.
Note : There are four public methods for IDentified scripting variable as follows String getDN() - returns DN String getStringAttribute( String attr ) - returns String value of named attribute String getStringAttribute( String attr, int idx ) - returns String value of named attribute for specified index Attribute getAttribute( String attr ) - returns JNDI Attribute object of named attribute

Tag	getDN
Description	Returns distinguished name of the entry.
Attributes

Tag	getAttribute
Description	Retrieve the specified attribute from entry.
Attributes	name	The ldap attribute name you want to display.
	delimiter	If the attribute contains more than one value , you can specify how to separate the values. See query examples.
	index	If the attribute contains more than one value, you can specify the index of attribute you want to get.
	mimeType	If the attribute contains value other than string, you have to specify mime type of the value. For example to display gif image correctly, you can use image/gif as value. See examples/UserList2.jsp file for usage example.
	default	you can set this attribute specify deafult value if the attribute contains no data. See the examples for the usage of the attribute.

Tag	add
Description	Craetes an entry in the directory
Attributes	dn	Specify the dn of the entry that will be created.
	id	Name for scripting variable. See note for metods of binded object

Tag	addAttribute
Description	Adds attributes to the entry that is hold by add tag.
Attributes	name	Name of the attribute
	value	Value of the attribute
Note : There is one public method you can access via IDentified scripting variable. Here is the explaination of the method; void setAddAttribute(String <attribute_name>, Object <attribute_value> ) -- You can add attributes directly using this function. Example: <ldap:add dn="uid=dummy5,ou=employees,dc=airius,dc=com" id="newentry"> <% newentry.setAddAttribute("objectclass","top"); newentry.setAddAttribute("objectclass","person"); newentry.setAddAttribute("objectclass","inetorgperson"); newentry.setAddAttribute("objectclass","organizationalperson"); newentry.setAddAttribute("cn","dummy user1"); newentry.setAddAttribute("sn","dummy1"); newentry.setAddAttribute("givenname","user1"); %> </ldap:add>

Tag	modify
Description	Modifies entries.
Attributes	dn	Specify the dn of the entry that will be modified.
	id	Name for scripting variable. See note for metods of binded object

Tag	modifyAttribute
Description	Tells the which attributes will be modified and its value.
Attributes	name	Name of the attribute to be modified
	value	Value of the attribute
	type	Specify operations type. The options are: add, replace or remove. See the examples.
Note : There is one public method you can access via IDentified scripting variable. Here is the explaination of the method; void setModifyAttribute(String <attribute_name>, Object <attribute_value>, int <operationType>) -- operation type has 3 options ; ADD_ATTRIBUTE (1), REPLACE_ATTRIBUTE (2), REMOVE_ATTRIBUTE (3). Example; <ldap:modify dn="uid=dummy5,ou=employees,dc=airius,dc=com" id="modentry" > <% modentry.setModifyAttribute("givenname","bruce",1); // add attribute%> <% modentry.setModifyAttribute("cn","bruce adams",2); // replaces attribute%> <% modentry.setModifyAttribute("mail",null,3); // deletes attribute%> </ldap:modify>

Tag	delete
Description	Deletes the entry from the directory
Attributes	dn	The distinguished name of the entry will be deleted.

Tag	modifydn
Description	Modify RDN of the entry. Old entry will be removed automatically. Please check your directory server documentation about modifing distinguish name. This operation is interprated diffrentlly by directory servers.
Attributes	olddn	The distinguished name of the entry will be renamed.
	newdn	The new distinguished name for the entry you want to rename.
Example: <ldap:modifydn olddn="uid=testuser,ou=people,o=airius.com" newdn="uid=renameduser,ou=people,o=airius.com" />

** Underlined names indicate that attributes are required