directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elecha...@apache.org
Subject svn commit: r1415892 - in /directory/site/trunk/content/api: ./ groovy-api/ user-guide/
Date Sat, 01 Dec 2012 00:07:16 GMT
Author: elecharny
Date: Sat Dec  1 00:07:15 2012
New Revision: 1415892

URL: http://svn.apache.org/viewvc?rev=1415892&view=rev
Log:
Added various pages

Added:
    directory/site/trunk/content/api/groovy-api/4-groovy-ldap-build.mdtext
    directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext
    directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext
    directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext
    directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext
Modified:
    directory/site/trunk/content/api/user-guide.mdtext

Added: directory/site/trunk/content/api/groovy-api/4-groovy-ldap-build.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/groovy-api/4-groovy-ldap-build.mdtext?rev=1415892&view=auto
==============================================================================
--- directory/site/trunk/content/api/groovy-api/4-groovy-ldap-build.mdtext (added)
+++ directory/site/trunk/content/api/groovy-api/4-groovy-ldap-build.mdtext Sat Dec  1 00:07:15
2012
@@ -0,0 +1,83 @@
+Title: 4 - Groovy LDAP : Buildng the Software
+NavPrev: 2-groovy-ldap-implementation.html
+NavPrevText: 2 - Groovy LDAP Implementation
+NavUp: ../groovy-ldap.html
+NavUpText: Groovy LDAP
+NavNext: 
+NavNextText: 
+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.
+
+# 4 - Groovy LDAP : Buildng the Software
+
+## Building the software
+
+### Resolving the dependencies
+
+Groovy LDAP needs Java 5 to compile. Besides this, it has only one dependency: Groovy itself.
For LDAP communication, JNDI and its LDAP provider are used. These are part of the JDK since
ages. 
+
+In order to build the software, Apache ant is used. For dependency resolution we use [Ivy](http://incubator.apache.org/ivy).
You need to configure your ant tool to use Ivy. One option is to place the corresponding jar
file _ivy-1.4.1.jar_ (or later) in the _lib_ folder of your ant distribution.
+
+### Building with ant and ivy (deprecated)
+
+Simply change to the _groovyldap_ directory and type _ant_.
+ 
+    D:\Apache>cd groovyldap
+    D:\Apache\groovyldap>ant
+    Buildfile: build.xml
+    
+    prepare:
+        [mkdir] Created dir: D:\Apache\groovyldap\dist
+        [mkdir] Created dir: D:\Apache\groovyldap\dist\classes
+        [mkdir] Created dir: D:\Apache\groovyldap\lib
+    
+    resolve:
+    [ivy:retrieve] :: Ivy 1.4.1 - 20061109165313 :: http://ivy.jayasoft.org/ ::
+    
+    ...
+
+    jarfile:
+          [jar] Building jar: D:\Apache\groovyldap\dist\groovy-ldap.jar
+    
+    BUILD SUCCESSFUL
+    Total time: 7 seconds
+    D:\Apache\groovyldap>_
+
+Done.
+
+The jarfile which includes the software, _groovy-ldap.jar_, is created in the _dist_ directory.
Feel free to call _ant clean_ afterwards. 
+
+### Building with Maven
+
+We are changing the build process to Maven 2, in order to have the same build tool for all
sub projects within Apache Directory. 
+
+Simply change to the _groovyldap_ directory and type _mvn install_.
+ 
+    D:\Apache\groovyldap>mvn install
+    [INFO] Scanning for projects...
+    [INFO] -----------------------------------------------------------------
+    [INFO] Building Apache Directory Groovy LDAP
+    [INFO]    task-segment: [install]
+    [INFO] -----------------------------------------------------------------
+    ...
+    [INFO] -----------------------------------------------------------------
+    [INFO] BUILD SUCCESSFUL
+    [INFO] -----------------------------------------------------------------
+    [INFO] Total time: 25 seconds
+    [INFO] Finished at: Mon Mar 02 22:06:54 CET 2009
+    [INFO] Final Memory: 19M/38M
+    [INFO] -----------------------------------------------------------------
\ No newline at end of file

Modified: directory/site/trunk/content/api/user-guide.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide.mdtext?rev=1415892&r1=1415891&r2=1415892&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide.mdtext (original)
+++ directory/site/trunk/content/api/user-guide.mdtext Sat Dec  1 00:07:15 2012
@@ -45,9 +45,8 @@ We are quite interested to improve the c
 
 ### Table of contents
 
-* [1 - Introduction](1-introduction.html)
-
-    Java and LDAP
+* [1 - Introduction](user-guide/1-introduction.html)
+  *  [Java and LDAP](user-guide/1.1-java-and-ldap.html)
     LDAP in a few words
     The Apache LDAP API rational
     Preparation to code

Added: directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext?rev=1415892&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext Sat Dec  1 00:07:15
2012
@@ -0,0 +1,46 @@
+Title: 1.1 - Java and LDAP
+NavPrev: 1-introduction.html
+NavPrevText: 1 - Introduction
+NavUp: 1-introduction.html
+NavUpText: 1 - Introduction
+NavNext: 1.2-ldap-in-a-few-words.html
+NavNextText: 1.2 - LDAP in a few words
+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.
+
+# 1.1 - Java and LDAP
+Most developer will, at some point, face the tricky task to communicate with a LDAP server.
LDAP seems to be a very simple technology, but when you get deep into it, you realize that
many aspects are not well known, and not so easy to deal with.
+
+Java is most certainly the number one language used in the enterprise, for around 10 years
now. Some even call it the new Cobol !
+
+Those two facts make it necessary to be able to communicate with a LDAP server in Java. This
is ware a convenient API is useful, and this is why we decided to provide this API.
+
+Of course, there are alternatives, like JNDI. We truly believe that those alternative aren't
helping users to cope with the complexity of LDAP, at least they are not giving a hand to
users. For instance, JNDI semantic are far awy from *LDAP semantic. Let's see how different
it is :
+
+    * Bind : used in LDAP to authenticate a user, and to create an entry in JNDI
+    * Unbind : close the LDAP session in LDAP, delete an entry in JNDI
+    * Compare : this LDAP operation is mapped to a Search in JNDI
+    * Various properties have to be set in JNDI in order to connect or tweak the Search operation,
which is not convenient
+    * Attributes is case sensitive by default in JNDI, and they aren't schema aware
+    * Name in JNDI are not able to do a valid comparison in JNDI
+    * NamingEnumeration have to be explcitly closed in JNDI, as they aren't closed when you
disconnect, leading to some resource leaks.
+
+Some of those problems are also true for the existing LDAP API.
+
+All in all, writing application including some LDAP operations in Java is just a painful
task for most of the developers.
+
+Our target is to provide a better API, that will help them getting efficient with their LDAP
interaction.
\ No newline at end of file

Added: directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext?rev=1415892&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext Sat Dec  1
00:07:15 2012
@@ -0,0 +1,49 @@
+Title: 1.2 - LDAP in a few words
+NavPrev: 1.1-java-and-ldap.html
+NavPrevText: 1.1 - Java and LDAP
+NavUp: 1-introduction.html
+NavUpText: 1 - Introduction
+NavNext: 1.3-apache-ldap-api-rational.html
+NavNextText: 1.3 - The Apache LDAP API rational
+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.
+
+# 1.2 - LDAP in a few words
+
+**LDAP** is not a new technlology. It has been around since mid 1990, as a way to mitigate
the complexity of the **X.500** based servers access. It's name is an acronym for **L**ightweight
**D**irectory **A**ccess **P**rotocol. Soon after the first standard has been issued, the
first full *LDAP* server was written (ie, X.500 was pushed out of the equation).
+
+We will now use the term **LDAP** and **LDAP** server for respectively the protocole and
the server.
+
+## Features
+A **LDAP** server provides access to entries, stored in a backend. It offers an interrogation
mechanism allowing fast retrieval of entries. The data structure is hierarchical, and we use
a schema to manage the content of entries, plus the organisation of data.
+
+A **LDAP** client first has to connect to the server, and disconnect at the end. Some operations
can be done on data, searches, modification and deletion, among a few others.
+
+**LDAP** servers are extensible, but they all use a common protocol which makes it easy for
users to request them. This API is an exemple of what **LDAP** is very good at : access data
in a fast way, across servers.
+
+## Characteristics
+**LDAP** servers are fast for retrievals : they have been designed for this purpose. On the
other hand, modifications can be costly. This has to be understood when writing an application
using a **LDAP** server as a backend.
+
+Each entry is identified by it's position in the hierarchy, and we use what is called a **D**istinguished
**N**ame (or **Dn**) to describe this position in the tree. The base is also named the **DIT**,
or **D**irectory **I**nformation **T**ree.
+
+## Programming 
+
+Nowadays, **LDAP** is a part of the **IT** and it's difficult to avoid having to deal with
it. **LDAP** servers are used to manage authentication, mainly, but also authorization, and
more. It's very likely that you will have to write some code to access such a **LDAP** server,
and the existing **API** are a bit cumbersome. This new **LDAP API** has been defined to facilitate
this kind of tasks.
+
+## Going further
+
+This was a very short introduction, you can find more literature about **LDAP** on the web
: [Wikipedia](http://en.wikipedia.org/wiki/LDAP) gives you a good starting point with many
valid pointers.

Added: directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext?rev=1415892&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext Sat Dec
 1 00:07:15 2012
@@ -0,0 +1,58 @@
+Title: 1.3 - The Apache LDAP API rational
+NavPrev: 1.2-ldap-in-a-few-words.html
+NavPrevText: 1.2 - LDAP in a few words
+NavUp: 1-introduction.html
+NavUpText: 1 - Introduction
+NavNext: 1.4-preparation-to-code.html
+NavNextText: 1.4 - Preparation to code
+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.
+
+# 1.3 - The Apache LDAP API rational
+
+Once we start to think about creating a new **LDAP** **API**, the first thing that comes
to mind is that it could be a duplication of effort : there are already many libraries offering
almost everything needed to write **LDAP** code. Some of them are :
+
+    * **JNDI** : the default **JDK** **API**
+    * **Netscape** [LdapSdk](http://www.mozilla.org/directory/javasdk.html)
+    * **OpenLDAP** [JLdap](http://www.openldap.org/jldap/)
+
+So what makes the development of a new *LDAP JAVA API* a valid effort, and not another version
of **[NIH](http://en.wikipedia.org/wiki/Not_Invented_Here)** syndrom ?
+
+There are many reasons why we decided to start to work on such an **API**, and we will expose
them in this chapter.
+
+## history
+The Apache Directory Server project was first built on top of **JNDI**, but many of the internal
**LDAP** structure were developed internally, just because **JNDI** was not designed specifically
for **LDAP**, so it was not convenient for us to use those structure. Step by step, all of
the **LDAP** objects (_Attribute_, _Entry_, _DN_, ...) were implemented again.
+
+At some point, we needed to communicate with another **LDAP** server without having to go
through **JNDI**, so we developed our own _LdapConnection_ class. This was the last step toward
a full **Java API**.
+
+Strange enough, at the very same time in 2007, the **Sun** people working on **OpenDS** contacted
us to know if we would agree to work on what would have become the next version of **JNDI**
([Resurrecting The Java LDAP Centric API](https://blogs.oracle.com/treydrake/entry/resurrecting_the_java_ldap_centric).
Sadly, this effort soon staled, as it seemed that *JNDI2* was not anymore an urgency for **Sun**.
We decided to go on but the pace was slow.
+
+We started again to work on this API with the **OpenDS** team in 2009, and did a presentation
during the 2009 **LdapCon** ([Towards a common LDAP API for the Java Platform](http://www.symas.com/ldapcon2009/papers/poitou1.shtml)).
The story repeated itself with **Oracle** buying **Sun** in 2010, after months of valuable
collaboration with *Sun*.
+
+At least, we get some kind of convergence in many aspects of the **API**. We agreed on some
of the key features the new **LDAP API** should offer :
+
+    * A complete coverage of the **LDAP** protocol
+    * A schema aware **API**
+    * An easy to use **API**
+    * An **API** taking advantage of the new **Java** construction (generics, ellipsis, NIO)
+
+## Result
+The newly defined **API** fulfill all those aspects. 
+
+We also wanted to make this **API** available for the masses. The Apache Software Foundation
value quality and community over code, which means we think that the code is the result of
a collaborative work, our users being a part of this collaboration. Every bug a user find,
it's an opportunity to provide a better version of the **API**.
+
+At he end, we are proud to deliver an **API** which is used in the Apache Directory Server,
but also in the Ldap Browser. 
\ No newline at end of file

Added: directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext?rev=1415892&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext Sat Dec  1
00:07:15 2012
@@ -0,0 +1,40 @@
+Title: 1.4 - Preparation to code
+NavPrev: 1.3-apache-ldap-api-rational.html
+NavPrevText: 1.3 - The Apache LDAP API rational
+NavUp: 1-introduction.html
+NavUpText: 1 - Introduction
+NavNext: 2-basic-ldap-api-usage.html
+NavNextText: 2 - Basic LDAP API Usage
+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.
+
+# 1.4 - Preparation to code
+
+In order to develop with the **Apache Directory LDAP API**, you first have to use a **Java
5** JDK or higher. 
+
+Second, you have to download the **[API](http://directory.apache.org/api/downloads.html)**.
This package contains not only the **LDAP API**, but also all the needed jars (like _commons-lang_,
_slf4j_...).
+
+If you are using **Maven**, you don't even have to refer all the libraries that are found
in the package, they will be deduced automatically. You will just have to add a dependency
on _shared-all.jar_ :
+
+    :::XML
+    <dependency>
+      <groupId>org.apache.directory.shared</groupId>
+      <artifactId>shared-all</artifactId>
+    </dependency>
+
+
+This is it, you should be ready to code !
\ No newline at end of file



Mime
View raw message