You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by pa...@apache.org on 2012/10/02 16:07:52 UTC
svn commit: r1392920 - in /directory/site/trunk/content:
api/five-minutes-tutorial.mdtext css/common.css
Author: pamarcelot
Date: Tue Oct 2 14:07:52 2012
New Revision: 1392920
URL: http://svn.apache.org/viewvc?rev=1392920&view=rev
Log:
Added the five minute tutorial API page. Added code highlighting classes to the CSS.
Added:
directory/site/trunk/content/api/five-minutes-tutorial.mdtext
Modified:
directory/site/trunk/content/css/common.css
Added: directory/site/trunk/content/api/five-minutes-tutorial.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/five-minutes-tutorial.mdtext?rev=1392920&view=auto
==============================================================================
--- directory/site/trunk/content/api/five-minutes-tutorial.mdtext (added)
+++ directory/site/trunk/content/api/five-minutes-tutorial.mdtext Tue Oct 2 14:07:52 2012
@@ -0,0 +1,118 @@
+Title: Five Minutes Tutorial
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# 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 :
+
+ :::java
+ 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 :
+
+ :::java
+ 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 :
+
+ :::java
+ // 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 :
+
+ :::java
+ 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 :
+
+ :::java
+ 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 :
+
+ :::java
+ 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](user-guide.html)**
Modified: directory/site/trunk/content/css/common.css
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/css/common.css?rev=1392920&r1=1392919&r2=1392920&view=diff
==============================================================================
--- directory/site/trunk/content/css/common.css (original)
+++ directory/site/trunk/content/css/common.css Tue Oct 2 14:07:52 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