directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elecha...@apache.org
Subject svn commit: r1463054 - /directory/site/trunk/content/api/user-guide/
Date Sun, 31 Mar 2013 21:21:15 GMT
Author: elecharny
Date: Sun Mar 31 21:21:14 2013
New Revision: 1463054

URL: http://svn.apache.org/r1463054
Log:
Added some missing pages

Added:
    directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext
    directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext
    directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext
      - copied, changed from r1417817, directory/site/trunk/content/api/user-guide/7-ldap-rfcs.mdtext
Removed:
    directory/site/trunk/content/api/user-guide/7-ldap-rfcs.mdtext
Modified:
    directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
    directory/site/trunk/content/api/user-guide/2.4-adding.mdtext
    directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext
    directory/site/trunk/content/api/user-guide/3-advanced-ldap-api-usage.mdtext
    directory/site/trunk/content/api/user-guide/6-ldap-data-structures.mdtext

Modified: directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext?rev=1463054&r1=1463053&r2=1463054&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext Sun Mar
31 21:21:14 2013
@@ -24,7 +24,7 @@ Notice: Licensed to the Apache Software 
 
 # 2.1 - Connection and disconnection
 
-**LDAP** is a protocol which requires the user to be connected - and eventually identified
- in order to be able to send requests to the server. We maintain this connection potentially
forever. What make the **LDAP** protocol different from, say, the *HTTP* protocol is that
the connection must be issued explicitly. Let's see how we do that.
+**LDAP** is a protocol which requires the user to be connected - and eventually identified
- in order to be able to send requests to the server. We maintain this connection potentially
forever. What make the **LDAP** protocol different from, say, the **HTTP** protocol is that
the connection must be issued explicitly. Let's see how we do that.
 
 ## Opening a connection
 

Modified: directory/site/trunk/content/api/user-guide/2.4-adding.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.4-adding.mdtext?rev=1463054&r1=1463053&r2=1463054&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.4-adding.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.4-adding.mdtext Sun Mar 31 21:21:14 2013
@@ -50,7 +50,7 @@ Here is two examples where we inject the
         assertTrue( session.exists( "cn=testadd,ou=system" ) );
     }
 
-In this basic example, we are adding a new entry, created using some **LDIF** formatted parameters,
the first one being the entry's Dn.
+In this basic example, we are adding a new entry, created using some **LDIF** formatted parameters,
the first one being the entry's _Dn_.
 Note that it is possible to use some variables in the **LDIF** instead of pure text. Here
is the same example, resulting to the same entry being added:
 
     :::Java
@@ -75,9 +75,9 @@ Note that it is possible to use some var
         assertTrue( session.exists( "cn=testadd,ou=system" ) );
     }
 
-Down the line, what is important is that the _add()_ operation is taking a full **[Entry]()**.

+Down the line, what is important is that the _add()_ operation is taking a full **[Entry](6.12-entry.html)**.

 
-We can also create the **[Entry]()** in a different way, which will be exposed in the following
paragraphs.
+We can also create the **[Entry](6.12-entry.html)** in a different way, which will be exposed
in the following paragraphs.
 
 ## Sending an **[AddRequest]()**
 

Modified: directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext?rev=1463054&r1=1463053&r2=1463054&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext Sun Mar 31 21:21:14 2013
@@ -22,4 +22,107 @@ Notice: Licensed to the Apache Software 
     specific language governing permissions and limitations
     under the License.
 
-# 2.5 - Deleting entries
\ No newline at end of file
+# 2.5 - Deleting entries
+
+Deleting an entry is really easy. It's just a matter to know its **[Dn]()**. There is one
important thing to understand though : if this entry has some children, it won't be deleted.
+
+## Simple entry deletion
+
+We can ask the deletion by providing the entry's **[Dn]()**, like what is done in the following
example :
+
+    :::Java
+    @Test
+    public void testDeleteLeafNode() throws Exception
+    {
+        assertTrue( session.exists( "cn=child1,cn=parent,ou=system" ) );
+
+        DeleteResponse response = connection.delete( "cn=child1,cn=parent,ou=system" );
+        assertNotNull( response );
+        assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult().getResultCode() );
+
+        assertFalse( session.exists( "cn=child1,cn=parent,ou=system" ) );
+    }
+
+
+Trying to delete the parent alone would leads to an error (NOT_ALLOWED_ON_NON_LEAF) :
+
+    :::Java
+    @Test
+    public void testDeleteNonLeafFailure() throws Exception
+    {
+        assertTrue( session.exists( "cn=parent,ou=system" ) );
+
+        DeleteResponse response = connection.delete( "cn=parent,ou=system" );
+        assertNotNull( response );
+        assertEquals( ResultCodeEnum.NOT_ALLOWED_ON_NON_LEAF, response.getLdapResult().getResultCode()
);
+
+        assertTrue( session.exists( "cn=parent,ou=system" ) );
+    }
+
+
+## Recursive deletion of entries
+
+Usually, you can't delete an entry and all of its children. However, some server accept such
a request if you send a delete request and a TreeDelete control. This control is a [draft](http://tools.ietf.org/html/draft-armijo-ldap-treedelete-02),
which has been implemented by **Microsoft**, **OpenDS**, **OpenDJ**. It will delete all the
children and the entry itself. We don't use a normal _delete()_ method, there is a specific
method, _deleteTree()_. Here is an example :
+
+    :::Java
+    @Test
+    public void testDeleteWithCascadeControl() throws Exception
+    {
+        assertTrue( session.exists( "cn=parent,ou=system" ) );
+
+
+        DeleteResponse response = connection.deleteTree( "cn=parent,ou=system" );
+        assertNotNull( response );
+        assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult().getResultCode() );
+
+        assertFalse( session.exists( "cn=parent,ou=system" ) );
+    }
+
+
+## Sending a DeleteRequest with a control
+
+It's also possible to associate a **[Control]** with the delete request. In order to do that,
you have to create a **[DelRequest]()** instance. In the following example, we will add the
Delete Tree control (this make this call equivalent to the _deleteTree()_ method).
+
+    :::Java
+    @Test
+    public void testDeleteWithControl() throws Exception
+    {
+        assertTrue( session.exists( "cn=parent,ou=system" ) );
+
+        if ( connection.isControlSupported( "1.2.840.113556.1.4.805" ) )
+        {
+            DeleteRequest deleteRequest = new DeleteRequestImpl();
+            deleteRequest.setName( new Dn( "cn=parent,ou=system" ) );
+            Control deleteTreeControl = new OpaqueControl( "1.2.840.113556.1.4.805" );
+            deleteRequest.addControl( deleteTreeControl );
+    
+            DeleteResponse deleteResponse = connection.delete( deleteRequest );
+    
+            assertNotNull( deleteResponse );
+            assertEquals( ResultCodeEnum.SUCCESS, deleteResponse.getLdapResult().getResultCode()
);
+            assertFalse( session.exists( "cn=parent,ou=system" ) );
+        }
+    }
+
+
+## Asynchronous delete
+
+You can also decide to send an asynchronous delete request : the method will return a Future
that you can check later. You have to construct a **[DeleteRequest]** instance. Here is an
example :
+
+    :::Java
+    @Test
+    public void testDeleteAsync() throws Exception
+    {
+        assertTrue( session.exists( "cn=child,cn=parent,ou=system" ) );
+
+        DeleteRequest deleteRequest = new DeleteRequestImpl();
+        deleteRequest.setName( new Dn( "cn=child,cn=parent,ou=system" ) );
+
+        DeleteFuture deleteFuture = connection.deleteAsync( deleteRequest );
+
+        DeleteResponse deleteResponse = deleteFuture.get( 1000, TimeUnit.MILLISECONDS );
+
+        assertNotNull( deleteResponse );
+        assertEquals( ResultCodeEnum.SUCCESS, deleteResponse.getLdapResult().getResultCode()
);
+        assertFalse( session.exists( "cn=child,cn=parent,ou=system" ) );
+    }

Modified: directory/site/trunk/content/api/user-guide/3-advanced-ldap-api-usage.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/3-advanced-ldap-api-usage.mdtext?rev=1463054&r1=1463053&r2=1463054&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/3-advanced-ldap-api-usage.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/3-advanced-ldap-api-usage.mdtext Sun Mar 31
21:21:14 2013
@@ -30,6 +30,6 @@ Notice: Licensed to the Apache Software 
 * [Extended operations (e)](3.2-extended-operations.html)
 * [Referrals (e)](3.3-referrals.html)
 * [Aliases (e)](3.4-aliases.html)
-* [LDIF, DSML (...)](3.5-aliases.html)
-* [Abandonning an operation (e)](3.6-ldif-dsml.html)
+* [LDIF, DSML (...)](3.5-ldif-dsml.html)
+* [Abandonning an operation (e)](3.6-abandonning.html)
 * [Server informations (e)](3.7-server-informations.html)

Modified: directory/site/trunk/content/api/user-guide/6-ldap-data-structures.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/6-ldap-data-structures.mdtext?rev=1463054&r1=1463053&r2=1463054&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/6-ldap-data-structures.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/6-ldap-data-structures.mdtext Sun Mar 31 21:21:14
2013
@@ -3,8 +3,8 @@ NavPrev: 5-ldap-security.html
 NavPrevText: 5 - LDAP Security
 NavUp: ../user-guide.html
 NavUpText: User Guide
-NavNext: 7-ldap-rfcs.html
-NavNextText: 7 - LDAP Related RFCs
+NavNext: 7-requests-response.html
+NavNextText: 7 - Requests and Responses
 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

Added: directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext?rev=1463054&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext Sun Mar 31 21:21:14
2013
@@ -0,0 +1,161 @@
+Title: 7 - Requests and Responses
+NavPrev: 6-ldap-data-structures.html
+NavPrevText: 6 - LDAP Data Structures
+NavUp: ../user-guide.html
+NavUpText: User Guide
+NavNext: 8-ldap-rfcs.html
+NavNextText: 8 - LDAP Related RFCs
+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.
+
+# 7 - Requests and Responses (...)
+
+We will describe all the Java structure we use for each LDAP message (Requests and Responses).
This can be useful when one want to send a message or process a response, using all the possible
options.
+
+## Inherited classes
+
+All the messages inherit from a few classes that are describe here. They gather the common
fields that can be used by most of the specific messages.
+
+### The Message interface
+
+This is the mother of all the hierarchy. A message has a few characteristics that are available
to all the inherited classes :
+
+    * Id : the message ID which is generated by the server or the client. You should never
add it
+    * Controls : The list of controls you add to a request or that get added by the response
+
+Here is the Message interface :
+
+    :::Java
+    /**
+     * Root interface for all LDAP message type interfaces.
+     * 
+     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+     */
+    public interface Message
+    {
+        /**
+         * Gets the LDAP message type code associated with this Message. Each
+         * request and response type has a unique message type code defined by the
+         * protocol in <a href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a>.
+         * 
+         * @return the message type code.
+         */
+        MessageTypeEnum getType();
+
+
+        /**
+         * Gets the controls associated with this message mapped by OID.
+         * 
+         * @return Map of OID strings to Control object instances.
+         */
+        Map<String, Control> getControls();
+
+
+        /**
+         * Gets the control associated with the given OID.
+         * 
+         * @param oid The Cntrol's OID we are looking for
+         * @return The Control object instance with the OID.
+         */
+        Control getControl( String oid );
+
+
+        /**
+         * Checks whether or not this message has the specified control.
+         *
+         * @param oid the OID of the control
+         * @return true if this message has the control, false if it does not
+         */
+        boolean hasControl( String oid );
+
+
+        /**
+         * Adds a control to this Message.
+         * 
+         * @param control the control to add.
+         * @return A Message reference
+         * @throws org.apache.directory.shared.ldap.model.exception.MessageException if controls
cannot be added to this Message or the control is
+         *             not known etc.
+         */
+        Message addControl( Control control ) throws MessageException;
+
+
+        /**
+         * Adds an array of controls to this Message.
+         * 
+         * @param controls the controls to add.
+         * @return A Message reference
+         * @throws MessageException if controls cannot be added to this Message or they are
not known etc.
+         */
+        Message addAllControls( Control[] controls ) throws MessageException;
+
+
+        /**
+         * Deletes a control removing it from this Message.
+         * 
+         * @param control the control to remove.
+         * @return A Message reference
+         * @throws MessageException if controls cannot be added to this Message or the control
is
+         *             not known etc.
+         */
+        Message removeControl( Control control ) throws MessageException;
+
+
+        /**
+         * Gets the session unique message sequence id for this message. Requests
+         * and their responses if any have the same message id. Clients at the
+         * initialization of a session start with the first message's id set to 1
+         * and increment it with each transaction.
+         * 
+         * @return the session unique message id.
+         */
+        int getMessageId();
+
+
+        /**
+         * Sets the Message ID for this request
+         * @param messageId The message Id
+         * @return A Message reference
+         */
+        Message setMessageId( int messageId );
+    }
+
+
+## Contents
+
+    * [7.1 - AbandonRequest](7.1-abandon-request.html)
+    * [7.2 - AddRequest](7.2-add-request.html)
+    * [7.3 - AddResponse](7.3-add-response.html)
+    * [7.4 - BindRequest](7.4-bind-request.html)
+    * [7.5 - BindResponse](7.5-bind-response.html)
+    * [7.6 - CompareRequest](7.6-compare-request.html)
+    * [7.7 - CompareResponse](7.7-compare-response.html)
+    * [7.8 - DelRequest](7.8-del-request.html)
+    * [7.9 - DelResponse](7.9-del-response.html)
+    * [7.10 - ExtendedRequest](7.10-extended-request.html)
+    * [7.11 - ExtendedResponse](7.11-extended-response.html)
+    * [7.12 - IntermediateResponse](7.12-intermediate-response.html)
+    * [7. - Message Interface](7.message-interface.html)
+    * [7.13 - ModDnRequest](7.13-mod-dn-request.html)
+    * [7.14 - ModDnResponse](7.14-mod-dn-response.html)
+    * [7.15 - ModifyRequest](7.15-modify-request.html)
+    * [7.16 - ModifyResponse](7.16-modify-response..html)
+    * [7.17 - SearchRequest](7.17-search-request.html)
+    * [7.18 - SearchResultDone](7.18-search-result-done.html)
+    * [7.19 - SearchResultEntry](7.19-search-result-entry.html)
+    * [7.20 - SearchResultReference](7.20-search-result-reference.html)
+    * [7.21 - UnbindRequest](7.21-unbind-request.html)

Added: directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext?rev=1463054&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext Sun Mar 31 21:21:14
2013
@@ -0,0 +1,78 @@
+Title: 7.1 - AbandonRequest
+NavPrev: 7-requests-responses.html
+NavPrevText: 7 - Requests and Responses
+NavUp: 7-requests-responses.html
+NavUpText: 7 - Requests and Responses
+NavNext: 7.2-add-request.html
+NavNextText: 7.2 - AddRequest
+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.
+
+# 7.1 AbandonRequest
+
+This request is used to tell the server that a given previous request must be abandonned.
The only needed parameter is the *ID* of the request you want to stop. 
+
+    :::Java
+    public interface AbandonRequest extends Request
+    {
+        /**
+         * Gets the id of the request operation to terminate.
+         * 
+         * @return the id of the request message to abandon
+         */
+        int getAbandoned();
+
+
+        /**
+         * Sets the id of the request operation to terminate.
+         * 
+         * @param requestId the sequence id of the request message to abandon
+         * @return The AbandonRequest instance
+         */
+        AbandonRequest setAbandoned( int requestId );
+    }
+
+There are two existing implementations you can use :
+
+* _AbandonRequestImpl_ : The default implementation.
+* _AbandonRequestDsml_ : An implementation used when you want to generate a DSML request
+
+The _AbandonRequest_ message does not have a response, the abandonned request will just be
stopped.
+
+## Usage
+
+It's pretty easy. You just have inject the ID of the request you want to abandon :
+
+    :::Java
+    connection.abandon( messageId );
+
+This will interrupt the request which ID is _messageId_.
+
+### Adding some controls
+
+You can add a control in the _AbandonRequest_, as soon as you create an instance of _AbandonRequestImpl
:
+
+
+    :::Java
+    AbandonRequest abandonRequest = new AbandonRequestImpl( messageId );
+
+    // Add your control 
+    abandonRequest.addControl( control );
+
+    // Send the request
+    connection.abandon( abandonRequest );
+_
\ No newline at end of file

Copied: directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext (from r1417817, directory/site/trunk/content/api/user-guide/7-ldap-rfcs.mdtext)
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext?p2=directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext&p1=directory/site/trunk/content/api/user-guide/7-ldap-rfcs.mdtext&r1=1417817&r2=1463054&rev=1463054&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/7-ldap-rfcs.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext Sun Mar 31 21:21:14 2013
@@ -1,6 +1,6 @@
-Title: 7 - LDAP Related RFCs
-NavPrev: 6-ldap-data-structures.html
-NavPrevText: 6 - LDAP Data Structures
+Title: 8 - LDAP Related RFCs
+NavPrev: 7-requests-response.html
+NavPrevText: 7 - Requests and Responses
 NavUp: ../user-guide.html
 NavUpText: User Guide
 NavNext: 
@@ -22,7 +22,7 @@ Notice: Licensed to the Apache Software 
     specific language governing permissions and limitations
     under the License.
 
-# 7 - LDAP Related RFCs
+# 8 - LDAP Related RFCs
 
 **LDAP** and **X.500** are specified through many **RFCs**. Here is the list of available
**RFCs** within some category (there are around 100 RFCs available, some of them are now deprecated,
some other are obsolete.
 



Mime
View raw message