Author: buildbot Date: Tue Oct 2 14:07:56 2012 New Revision: 833748 Log: Staging update by buildbot for directory Added: websites/staging/directory/trunk/content/api/five-minutes-tutorial.html Modified: websites/staging/directory/trunk/content/ (props changed) websites/staging/directory/trunk/content/css/common.css Propchange: websites/staging/directory/trunk/content/ ------------------------------------------------------------------------------ --- cms:source-revision (original) +++ cms:source-revision Tue Oct 2 14:07:56 2012 @@ -1 +1 @@ -1392919 +1392920 Added: websites/staging/directory/trunk/content/api/five-minutes-tutorial.html ============================================================================== --- websites/staging/directory/trunk/content/api/five-minutes-tutorial.html (added) +++ websites/staging/directory/trunk/content/api/five-minutes-tutorial.html Tue Oct 2 14:07:56 2012 @@ -0,0 +1,189 @@ + + + + + Five Minutes Tutorial — Apache Directory + + + + + + +
+ +
+
+ + + +
+
+ +

Five Minutes Tutorial

+

Introduction

+
+

Warning: This is a very preliminary tutorial, the user must be informed that the current implementation will evolve a lot in the near future. So will the tutorial, hopefully...

+
+

This new API has been created in order to offer a better API than what we currently use, namely JNDI or older API like LdapSDK or jldap. It benefits from some improvements brought by ApacheDS and OpenDS.

+

This 5-minutes tutorial will present the way to use this API when working with a LDAP server.

+

Base principles

+

LDAP is a connected protocol, so you need to create a connection in order to send request and receive response from a Ldap server. This is the main point : you have to create a connection first.

+

Each operation can have one or more responses, and produce exceptions when something went wrong.

+

The API is schema ware, ie the manipulated objects will be controlled on the client side, assuming you have brought back the schema from the server, or by using a default schema configuration

+

Connection

+

In order to create a connection, you first have to provide the name of the server, and the port to use. Those parameters will be defaulted to localHost and 389 if nothing is defined.

+

Opening a connection

+

Here is an example :

+
LdapConnection connection = new LdapConnection( "localhost", 389 );
+
+ + +

It's important to note that the connection has nothing to do with being bound, and this is a major difference with JNDI, where you create some context and provide the principalDN. A Connection is just a channel opened with the server, here.

+

Another important thing to understand is that the connection is not explicitly opened. In fact, the bind operation will open the connection.

+

Secure connection

+
+

TODO

+
+

Bind operation

+

Now that the connection has been created, you can call the bind() method. This will create a identified connection between a client and the server. The bind operation has nothing to do with the JNDI bind, as no entry will be created.

+

Anonymous bind

+

You can bind using no identifier, and in this case, you'll create an anonymous LDAP session. This is done this way :

+
connection.bind();
+
+ + +

Simple bind

+

The most common bind uses an identifier and a password. The identifier must be a DN, and the password can be encrypted. Here is an example of a bind operation :

+
// Don't do that ! Password in clear text = danger !
+connection.bind( "ou=example, dc=com", "secret" );
+
+// The password is encrypted, but it does not protect against a MITM attack
+connection.bind( "ou=example, dc=com", "{crypt}wSiewPyxdEC2c" );
+
+ + +

Search operation

+

We have tried to make it easy to search information in a LDAP server, as this is the most frequently used operation.

+

Many parameters can be used in a search. The most commonly used are : + The base DN + The filter + The scope + The returning attributes list

+

Simple search operation

+

Here is a simple search, done using only those four parameters :

+
Cursor<SearchResponse> cursor = connection.search( "ou=system", "(objectclass=*)", SearchScope.ONELEVEL, "*" );
+
+while ( cursor.next() )
+{
+    SearchResponse response = cursor.get();
+
+    // Process the response
+    ...
+}
+
+ + +

Here, we call the search operation, and we get back a cursor. Reading search result from the cursor is done with the get() method, moving forward uses the next() method.

+

Unbinding

+

When you are done with the operation, you can unbind. This is done by calling the unbind() method, this way :

+
connection.unbind();
+
+ + +

Closing the connection

+

Once you are done with the connection, don't forget to close it. It's done by calling the close() method :

+
connection.close();
+
+ + +

If you explicitly call the unbind() method, the connection will also be closed, and in this case, you wont have to close it explicitly.

+

Conclusion

+

This very limited presentation was written to give users a quick insight about how to use the API. In order to get some further information, please check the User Guide

+ +
+
+
+ +
+ + \ No newline at end of file Modified: websites/staging/directory/trunk/content/css/common.css ============================================================================== --- websites/staging/directory/trunk/content/css/common.css (original) +++ websites/staging/directory/trunk/content/css/common.css Tue Oct 2 14:07:56 2012 @@ -533,4 +533,68 @@ th .download td { padding: 0; -} \ No newline at end of file +} + + +.codehilite .hll { background-color: #ffffcc } +.codehilite { background: #f0f0f0; } +.codehilite .c { color: #60a0b0; font-style: italic } /* Comment */ +.codehilite .err { border: 1px solid #FF0000 } /* Error */ +.codehilite .k { color: #007020; font-weight: bold } /* Keyword */ +.codehilite .o { color: #666666 } /* Operator */ +.codehilite .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */ +.codehilite .cp { color: #007020 } /* Comment.Preproc */ +.codehilite .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */ +.codehilite .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */ +.codehilite .gd { color: #A00000 } /* Generic.Deleted */ +.codehilite .ge { font-style: italic } /* Generic.Emph */ +.codehilite .gr { color: #FF0000 } /* Generic.Error */ +.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.codehilite .gi { color: #00A000 } /* Generic.Inserted */ +.codehilite .go { color: #808080 } /* Generic.Output */ +.codehilite .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.codehilite .gs { font-weight: bold } /* Generic.Strong */ +.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.codehilite .gt { color: #0040D0 } /* Generic.Traceback */ +.codehilite .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.codehilite .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.codehilite .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.codehilite .kp { color: #007020 } /* Keyword.Pseudo */ +.codehilite .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.codehilite .kt { color: #902000 } /* Keyword.Type */ +.codehilite .m { color: #40a070 } /* Literal.Number */ +.codehilite .s { color: #4070a0 } /* Literal.String */ +.codehilite .na { color: #4070a0 } /* Name.Attribute */ +.codehilite .nb { color: #007020 } /* Name.Builtin */ +.codehilite .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.codehilite .no { color: #60add5 } /* Name.Constant */ +.codehilite .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.codehilite .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.codehilite .ne { color: #007020 } /* Name.Exception */ +.codehilite .nf { color: #06287e } /* Name.Function */ +.codehilite .nl { color: #002070; font-weight: bold } /* Name.Label */ +.codehilite .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.codehilite .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.codehilite .nv { color: #bb60d5 } /* Name.Variable */ +.codehilite .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.codehilite .w { color: #bbbbbb } /* Text.Whitespace */ +.codehilite .mf { color: #40a070 } /* Literal.Number.Float */ +.codehilite .mh { color: #40a070 } /* Literal.Number.Hex */ +.codehilite .mi { color: #40a070 } /* Literal.Number.Integer */ +.codehilite .mo { color: #40a070 } /* Literal.Number.Oct */ +.codehilite .sb { color: #4070a0 } /* Literal.String.Backtick */ +.codehilite .sc { color: #4070a0 } /* Literal.String.Char */ +.codehilite .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.codehilite .s2 { color: #4070a0 } /* Literal.String.Double */ +.codehilite .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.codehilite .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.codehilite .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.codehilite .sx { color: #c65d09 } /* Literal.String.Other */ +.codehilite .sr { color: #235388 } /* Literal.String.Regex */ +.codehilite .s1 { color: #4070a0 } /* Literal.String.Single */ +.codehilite .ss { color: #517918 } /* Literal.String.Symbol */ +.codehilite .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.codehilite .vc { color: #bb60d5 } /* Name.Variable.Class */ +.codehilite .vg { color: #bb60d5 } /* Name.Variable.Global */ +.codehilite .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.codehilite .il { color: #40a070 } /* Literal.Number.Integer.Long */ \ No newline at end of file