You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by gi...@apache.org on 2021/05/20 02:04:50 UTC
[directory-site] branch asf-site updated: Updated site from master
(11c22a743c616556363f36ac1afdcb6341289183)
This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/directory-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 90b6d2a Updated site from master (11c22a743c616556363f36ac1afdcb6341289183)
90b6d2a is described below
commit 90b6d2ab02e29f3af05c86a6e9aaaffd93d962ab
Author: jenkins <bu...@apache.org>
AuthorDate: Thu May 20 02:04:46 2021 +0000
Updated site from master (11c22a743c616556363f36ac1afdcb6341289183)
---
content/api/index.xml | 6 +-
.../14-extended-operations.html | 1805 ++++++++++----------
content/api/internal-design-guide/3-building.html | 44 +-
content/api/internal-design-guide/4-asn1.html | 6 +-
.../api/internal-design-guide/4.1-asn1-tlv.html | 948 +++++-----
.../user-guide/2.10-ldap-connection-template.html | 326 ++--
content/api/user-guide/2.2-binding-unbinding.html | 187 +-
content/api/user-guide/2.3-searching.html | 104 +-
content/api/user-guide/2.4-adding.html | 172 +-
content/api/user-guide/2.5-deleting.html | 180 +-
content/api/user-guide/2.6-modifying.html | 421 +++--
content/fortress/coding-standards.html | 76 +-
content/index.xml | 6 +-
content/sitemap.xml | 26 +-
14 files changed, 2072 insertions(+), 2235 deletions(-)
diff --git a/content/api/index.xml b/content/api/index.xml
index ddc6330..e967b0c 100644
--- a/content/api/index.xml
+++ b/content/api/index.xml
@@ -118,7 +118,7 @@ Implementation Here is the Control classes and interfaces hierarchy :</descripti
<guid>https://directory.apache.org/api/internal-design-guide/14-extended-operations.html</guid>
<description>14 - Extended Operations Extended Operation is a LDAP message which may content a payload. It is generally sent by the clinet, but the server can send a ExtendedResponse as a response to any operation : the Notice of Disconnection.
Here is the syntax for the extended Operation :
-ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } (the payload is the requestValue or responseValue part, which may be BER encoded).</description>
+ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } (the payload is the requestValue or responseValue part, which may be BER encoded).</description>
</item>
<item>
@@ -241,7 +241,7 @@ Adding an entry Here is the simplest way to add an entry into the server, assumi
<guid>https://directory.apache.org/api/user-guide/2.5-deleting.html</guid>
<description>2.5 - Deleting entries Deleting an entry is pretty easy, it just requires the entry&rsquo;s DN. There is one important thing to understand though, if the entry has children, the operation will fail.
Simple entry deletion We request a deletion by providing the entry&rsquo;s DN, as in the following example:
-:::Java @Test public void testDeleteLeafNode() throws Exception { assertTrue( session.exists( &quot;cn=child1,cn=parent,ou=system&quot; ) ); try { connection.delete( &quot;cn=child1,cn=parent,ou=system&quot; ); } catch ( LdapException le ) { fail( le.</description>
+@Test public void testDeleteLeafNode() throws Exception { assertTrue( session.exists( &#34;cn=child1,cn=parent,ou=system&#34; ) ); try { connection.delete( &#34;cn=child1,cn=parent,ou=system&#34; ); } catch ( LdapException le ) { fail( le.</description>
</item>
<item>
@@ -299,7 +299,7 @@ Actually, changing an entry&rsquo;s name *may have an impact on the entry&am
<guid>https://directory.apache.org/api/internal-design-guide/3-building.html</guid>
<description>3 - Building The project is based on Apache Maven (version 3.x), so you&rsquo;ll have to install it first.
That being said, building the LDAP API is pretty straightforward :
-::: $ mvn clean install Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0 [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: [INFO] [INFO] Apache Directory LDAP API [INFO] Apache Directory LDAP API I18n [INFO] Apache Directory LDAP API Utilities .</description>
+$ mvn clean install Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0 [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: [INFO] [INFO] Apache Directory LDAP API [INFO] Apache Directory LDAP API I18n [INFO] Apache Directory LDAP API Utilities .</description>
</item>
<item>
diff --git a/content/api/internal-design-guide/14-extended-operations.html b/content/api/internal-design-guide/14-extended-operations.html
index 5028230..4f33dcf 100644
--- a/content/api/internal-design-guide/14-extended-operations.html
+++ b/content/api/internal-design-guide/14-extended-operations.html
@@ -159,16 +159,15 @@
<h1 id="14---extended-operations">14 - Extended Operations</h1>
<p><strong>Extended Operation</strong> is a <strong>LDAP</strong> message which may content a payload. It is generally sent by the clinet, but the server can send a <em>ExtendedResponse</em> as a response to any operation : the <strong>Notice of Disconnection</strong>.</p>
<p>Here is the syntax for the extended Operation :</p>
-<pre><code>ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
- requestName [0] LDAPOID,
- requestValue [1] OCTET STRING OPTIONAL }
-
-ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
- COMPONENTS OF LDAPResult,
- responseName [10] LDAPOID OPTIONAL,
- responseValue [11] OCTET STRING OPTIONAL }
-</code></pre>
-<p>(the payload is the <em>requestValue</em> or <em>responseValue</em> part, which may be <strong>BER</strong> encoded).</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+ requestName [0] LDAPOID,
+ requestValue [1] OCTET STRING OPTIONAL }
+
+ ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+ COMPONENTS OF LDAPResult,
+ responseName [10] LDAPOID OPTIONAL,
+ responseValue [11] OCTET STRING OPTIONAL }
+</code></pre></div><p>(the payload is the <em>requestValue</em> or <em>responseValue</em> part, which may be <strong>BER</strong> encoded).</p>
<p>This message is routinely decoded as is by the standard <strong>LDAP</strong> message decoder, but the payload has to be decoded on its own.</p>
<h2 id="supported-extended-operations">Supported extended operations</h2>
<p>Currently, the <strong>LDAP API</strong> support the following extended operations :</p>
@@ -186,826 +185,792 @@ ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
<p>When the <em>requestValue</em> part is present, it has to be encoded (when the client sends the request to the srrver) or decoded ( when the client receives the response from the server).</p>
<h3 id="decoding-a-requestresponse">Decoding a request/response</h3>
<p>The payload is decoded on the fly when the request/response is processed during the <em>extendedRequest</em>/<em>extendedResponse</em> is being decoded. The <em>StoreExtendedRequestValue</em>/<em>StoreExtendedResponseValue</em> will store the <em>byte[]</em> - if any - and depending on the operation, the specific request/response will decode the value. Here is the <em>action</em> method for the <em>StoreExtendedRequestValue</em> class :</p>
-<pre><code>:::Java
-public void action( LdapMessageContainer<ExtendedRequestDecorator<?>> container ) throws DecoderException
-{
- // We can allocate the ExtendedRequest Object
- ExtendedRequestDecorator<?> extendedRequest = container.getMessage();
-
- // Get the Value and store it in the ExtendedRequest
- TLV tlv = container.getCurrentTLV();
-
- // We have to handle the special case of a 0 length matched
- // value
- if ( tlv.getLength() == 0 )
- {
- extendedRequest.setRequestValue( Strings.EMPTY_BYTES );
- }
- else
- {
- extendedRequest.setRequestValue( tlv.getValue().getData() );
- }
-</code></pre>
-<p>Each implementaion may have a <em>setRequestValue</em>/<em>setResponseValue</em> methd, overloading the parentclass. In this case, the value is decoded by the method.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">action</span><span style="color:#666">(</span> LdapMessageContainer<span style="color:#666"><</span>ExtendedRequestDecorator<span style="color:#666"><</span><span style="color:#666">?</span><span s [...]
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">// We can allocate the ExtendedRequest Object
+</span><span style="color:#080;font-style:italic"></span> ExtendedRequestDecorator<span style="color:#666"><</span><span style="color:#666">?</span><span style="color:#666">></span> extendedRequest <span style="color:#666">=</span> container<span style="color:#666">.</span><span style="color:#b44">getMessage</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">// Get the Value and store it in the ExtendedRequest
+</span><span style="color:#080;font-style:italic"></span> TLV tlv <span style="color:#666">=</span> container<span style="color:#666">.</span><span style="color:#b44">getCurrentTLV</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">// We have to handle the special case of a 0 length matched
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#080;font-style:italic">// value
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> tlv<span style="color:#666">.</span><span style="color:#b44">getLength</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">=</span><span style="color:#666">=</span> 0 <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ extendedRequest<span style="color:#666">.</span><span style="color:#b44">setRequestValue</span><span style="color:#666">(</span> Strings<span style="color:#666">.</span><span style="color:#b44">EMPTY_BYTES</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">else</span>
+ <span style="color:#666">{</span>
+ extendedRequest<span style="color:#666">.</span><span style="color:#b44">setRequestValue</span><span style="color:#666">(</span> tlv<span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getData</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Each implementaion may have a <em>setRequestValue</em>/<em>setResponseValue</em> methd, overloading the parentclass. In this case, the value is decoded by the method.</p>
<p>Here is an example of <em>setRequestValue</em> implementation (for the <em>PasswordModifyRequest</em> class) :</p>
-<pre><code>:::Java
-public void setRequestValue( byte[] requestValue )
-{
- PasswordModifyRequestDecoder decoder = new PasswordModifyRequestDecoder();
-
- try
- {
- if ( requestValue != null )
- {
- passwordModifyRequest = decoder.decode( requestValue );
-
- this.requestValue = new byte[requestValue.length];
- System.arraycopy( requestValue, 0, this.requestValue, 0, requestValue.length );
- }
- else
- {
- this.requestValue = null;
- }
- }
- catch ( DecoderException e )
- {
- LOG.error( I18n.err( I18n.ERR_04165 ), e );
- throw new RuntimeException( e );
- }
-}
-</code></pre>
-<p>As we can see, the decoder is invoked if the <em>requestValue</em> bytes is not null. It instanciate a <em>PasswordModifyRequest</em>.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setRequestValue</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> requestValue <span style="c [...]
+ <span style="color:#666">{</span>
+ PasswordModifyRequestDecoder decoder <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> PasswordModifyRequestDecoder<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> requestValue <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ passwordModifyRequest <span style="color:#666">=</span> decoder<span style="color:#666">.</span><span style="color:#b44">decode</span><span style="color:#666">(</span> requestValue <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">requestValue</span> <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span>requestValue<span style="color:#666">.</span><span style="color:#b44">length</span><span style="color:#666">]</span><span style="color:#666">;</span>
+ System<span style="color:#666">.</span><span style="color:#b44">arraycopy</span><span style="color:#666">(</span> requestValue<span style="color:#666">,</span> 0<span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">requestValue</span><span style="color:#666">,</span> 0<span style="color:#666">,</span> requestValue<span style="color:#666">.</span><span style="color:#b44">length</span [...]
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">else</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">requestValue</span> <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> DecoderException e <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ LOG<span style="color:#666">.</span><span style="color:#b44">error</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">err</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">ERR_04165</span> <span style="color:#666">)</span><span style="color:#666">,</span> e <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">throw</span> <span style="color:#a2f;font-weight:bold">new</span> RuntimeException<span style="color:#666">(</span> e <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>As we can see, the decoder is invoked if the <em>requestValue</em> bytes is not null. It instanciate a <em>PasswordModifyRequest</em>.</p>
<p>If there is no payload, the parent’s method is invoked (which basically does nothing).</p>
<p>Here is a schema showing which request/response operations as a payload that needs to be decoded :</p>
<p><img src="images/extended-request-decorator.png" alt="Extended Operations Payload"></p>
<h3 id="encoding-a-requestresponse">Encoding a request/response</h3>
<p>Encoding is done through a <em>Decorator</em>. Each extended operation has a dedicated <em>Decorator</em>, which may have a specific encoding function. Again, as we only encode the payload, if this payload is absent, there is nothing to encode. Not all the extended operations have a payload.</p>
<p>If there is a payload to encode, this is done by calling the <em>getRequestValue()</em>/<em>getResponseValue()</em> method in the decorator. Here is an example :</p>
-<pre><code>:::Java
-public byte[] getRequestValue()
-{
- if ( requestValue == null )
- {
- try
- {
- requestValue = encodeInternal().array();
- }
- catch ( EncoderException e )
- {
- LOG.error( I18n.err( I18n.ERR_04167 ), e );
- throw new RuntimeException( e );
- }
- }
-
- return requestValue;
-}
-</code></pre>
-<p>The <em>encodeInternal</em> method is in charge of encoding teh paylod.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#00a000">getRequestValue</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> requestValue <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ requestValue <span style="color:#666">=</span> encodeInternal<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">array</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> EncoderException e <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ LOG<span style="color:#666">.</span><span style="color:#b44">error</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">err</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">ERR_04167</span> <span style="color:#666">)</span><span style="color:#666">,</span> e <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">throw</span> <span style="color:#a2f;font-weight:bold">new</span> RuntimeException<span style="color:#666">(</span> e <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> requestValue<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>The <em>encodeInternal</em> method is in charge of encoding teh paylod.</p>
<p>If the <em>getRequestValue</em>/getResponseValue_ method is absent, that leans there is nothing to encode. The inherited method will be executed, which returns null.</p>
<p>Internally, we compute the length of the needed <strong>PDU</strong> accordingly to the data we have to encode, allocate a <em>ByteBuffer</em> to hold the encoded data, and store teh encoded data into it :</p>
-<pre><code>:::Java
-/**
- * Encodes the PasswordModifyRequest extended operation.
- *
- * @return A ByteBuffer that contains the encoded PDU
- * @throws org.apache.directory.api.asn1.EncoderException If anything goes wrong.
- */
-/* No qualifier */ByteBuffer encodeInternal() throws EncoderException
-{
- ByteBuffer bb = ByteBuffer.allocate( computeLengthInternal() );
-
- bb.put( UniversalTag.SEQUENCE.getValue() );
- bb.put( TLV.getBytes( requestLength ) );
-
- if ( passwordModifyRequest.getUserIdentity() != null )
- {
- byte[] userIdentity = passwordModifyRequest.getUserIdentity();
- bb.put( ( byte ) PasswordModifyRequestConstants.USER_IDENTITY_TAG );
- bb.put( TLV.getBytes( userIdentity.length ) );
- bb.put( userIdentity );
- }
-
- if ( passwordModifyRequest.getOldPassword() != null )
- {
- byte[] oldPassword = passwordModifyRequest.getOldPassword();
- bb.put( ( byte ) PasswordModifyRequestConstants.OLD_PASSWORD_TAG );
- bb.put( TLV.getBytes( oldPassword.length ) );
- bb.put( oldPassword );
- }
-
- if ( passwordModifyRequest.getNewPassword() != null )
- {
- byte[] newPassword = passwordModifyRequest.getNewPassword();
- bb.put( ( byte ) PasswordModifyRequestConstants.NEW_PASSWORD_TAG );
- bb.put( TLV.getBytes( newPassword.length ) );
- bb.put( newPassword );
- }
-
- return bb;
-}
-</code></pre>
-<p>and the <em>computeLength</em> method is :</p>
-<pre><code>:::Java
-/**
- * Compute the PasswordModifyRequest extended operation length
- * <pre>
- * 0x30 L1
- * |
- * [+-- 0x80 L2 userIdentity]
- * [+-- 0x81 L3 oldPassword]
- * [+-- 0x82 L4 newPassword]
- * </pre>
- */
-/* No qualifier */int computeLengthInternal()
-{
- requestLength = 0;
-
- if ( passwordModifyRequest.getUserIdentity() != null )
- {
- int len = passwordModifyRequest.getUserIdentity().length;
- requestLength = 1 + TLV.getNbBytes( len ) + len;
- }
-
- if ( passwordModifyRequest.getOldPassword() != null )
- {
- int len = passwordModifyRequest.getOldPassword().length;
- requestLength += 1 + TLV.getNbBytes( len ) + len;
- }
-
- if ( passwordModifyRequest.getNewPassword() != null )
- {
- int len = passwordModifyRequest.getNewPassword().length;
- requestLength += 1 + TLV.getNbBytes( len ) + len;
- }
-
- return 1 + TLV.getNbBytes( requestLength ) + requestLength;
-}
-</code></pre>
-<h2 id="adding-a-new-extended-operation">Adding a new Extended operation</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Encodes the PasswordModifyRequest extended operation.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @return A ByteBuffer that contains the encoded PDU
+</span><span style="color:#080;font-style:italic"> * @throws org.apache.directory.api.asn1.EncoderException If anything goes wrong.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#080;font-style:italic">/* No qualifier */</span>ByteBuffer <span style="color:#00a000">encodeInternal</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> EncoderException
+ <span style="color:#666">{</span>
+ ByteBuffer bb <span style="color:#666">=</span> ByteBuffer<span style="color:#666">.</span><span style="color:#b44">allocate</span><span style="color:#666">(</span> computeLengthInternal<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> UniversalTag<span style="color:#666">.</span><span style="color:#b44">SEQUENCE</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> TLV<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> requestLength <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getUserIdentity</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> userIdentity <span style="color:#666">=</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getUserIdentity</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span> <span style="color:#666">)</span> PasswordModifyRequestConstants<span style="color:#666">.</span><span style="color:#b44">USER_IDENTITY_TAG</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> TLV<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> userIdentity<span style="color:#666">.</span><span style="color:#b44">length</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> userIdentity <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getOldPassword</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> oldPassword <span style="color:#666">=</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getOldPassword</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span> <span style="color:#666">)</span> PasswordModifyRequestConstants<span style="color:#666">.</span><span style="color:#b44">OLD_PASSWORD_TAG</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> TLV<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> oldPassword<span style="color:#666">.</span><span style="color:#b44">length</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> oldPassword <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getNewPassword</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> newPassword <span style="color:#666">=</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getNewPassword</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span> <span style="color:#666">)</span> PasswordModifyRequestConstants<span style="color:#666">.</span><span style="color:#b44">NEW_PASSWORD_TAG</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> TLV<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> newPassword<span style="color:#666">.</span><span style="color:#b44">length</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ bb<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> newPassword <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> bb<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>and the <em>computeLength</em> method is :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Compute the PasswordModifyRequest extended operation length
+</span><span style="color:#080;font-style:italic"> * <pre>
+</span><span style="color:#080;font-style:italic"> * 0x30 L1
+</span><span style="color:#080;font-style:italic"> * |
+</span><span style="color:#080;font-style:italic"> * [+-- 0x80 L2 userIdentity]
+</span><span style="color:#080;font-style:italic"> * [+-- 0x81 L3 oldPassword]
+</span><span style="color:#080;font-style:italic"> * [+-- 0x82 L4 newPassword]
+</span><span style="color:#080;font-style:italic"> * </pre>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#080;font-style:italic">/* No qualifier */</span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">computeLengthInternal</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ requestLength <span style="color:#666">=</span> 0<span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getUserIdentity</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> len <span style="color:#666">=</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getUserIdentity</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">length</span><span style="color:#666">;</span>
+ requestLength <span style="color:#666">=</span> 1 <span style="color:#666">+</span> TLV<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> len <span style="color:#666">)</span> <span style="color:#666">+</span> len<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getOldPassword</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> len <span style="color:#666">=</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getOldPassword</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">length</span><span style="color:#666">;</span>
+ requestLength <span style="color:#666">+</span><span style="color:#666">=</span> 1 <span style="color:#666">+</span> TLV<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> len <span style="color:#666">)</span> <span style="color:#666">+</span> len<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getNewPassword</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> len <span style="color:#666">=</span> passwordModifyRequest<span style="color:#666">.</span><span style="color:#b44">getNewPassword</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">length</span><span style="color:#666">;</span>
+ requestLength <span style="color:#666">+</span><span style="color:#666">=</span> 1 <span style="color:#666">+</span> TLV<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> len <span style="color:#666">)</span> <span style="color:#666">+</span> len<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> 1 <span style="color:#666">+</span> TLV<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> requestLength <span style="color:#666">)</span> <span style="color:#666">+</span> requestLength<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h2 id="adding-a-new-extended-operation">Adding a new Extended operation</h2>
<p>We will show how to add a new extended operation in the <strong>LDAP API</strong>. The added operation is the <em>startTransaction</em> operation, described in <a href="https://tools.ietf.org/html/rfc5805">RFC 5805</a>.</p>
<p>The <em>startTransactionRequest</em> has a <em>requestName</em> containing <strong>1.3.6.1.1.21.1</strong>, and no <em>requestValue</em>.
The <em>startTransactionResponse</em> has no <em>responseName</em> and a <em>responseValue</em> containing an opaque transaction identifier (ie, it does not need to be decoced).</p>
<p>We first need to declare an interface and implementation for each of those two operations. Those four elements are declared in the <em><coec-api></em> module (in <em>/ldap/extras/codec-api</em>), and in the <em>org.apache.directory.api.ldap.extras.extended.startTransaction</em> package, beside the other extended operations :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.startTransaction;
-
-
-import org.apache.directory.api.ldap.model.message.ExtendedRequest;
-
-
-/**
- * The TransactionRequest interface. This is for the RFC 5805 Start Transaction Request,
- * which grammar is :
- * <pre>
- * ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
- * requestName [0] LDAPOID,
- * requestValue [1] OCTET STRING OPTIONAL }
- * </pre>
- *
- * where 'requestName' is 1.3.6.1.1.21.1 and requestValue is absent.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public interface StartTransactionRequest extends ExtendedRequest
-{
- /** The OID for the Transaction extended operation request. */
- String EXTENSION_OID = "1.3.6.1.1.21.1";
-}
-</code></pre>
-<p>The request interface defines noting but the <em>OID</em>, as we don’t have any payload.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.ExtendedRequest</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * The TransactionRequest interface. This is for the RFC 5805 Start Transaction Request,
+</span><span style="color:#080;font-style:italic"> * which grammar is :
+</span><span style="color:#080;font-style:italic"> * <pre>
+</span><span style="color:#080;font-style:italic"> * ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+</span><span style="color:#080;font-style:italic"> * requestName [0] LDAPOID,
+</span><span style="color:#080;font-style:italic"> * requestValue [1] OCTET STRING OPTIONAL }
+</span><span style="color:#080;font-style:italic"> * </pre>
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * where 'requestName' is 1.3.6.1.1.21.1 and requestValue is absent.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">interface</span> <span style="color:#00f">StartTransactionRequest</span> <span style="color:#a2f;font-weight:bold">extends</span> ExtendedRequest
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The OID for the Transaction extended operation request. */</span>
+ String EXTENSION_OID <span style="color:#666">=</span> <span style="color:#b44">"1.3.6.1.1.21.1"</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>The request interface defines noting but the <em>OID</em>, as we don’t have any payload.</p>
<p>Here is the implementation :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.startTransaction;
-
-
-import org.apache.directory.api.ldap.model.message.AbstractExtendedRequest;
-
-
-/**
- * Implement the extended Start Transaction Request as described in RFC 5805.
- *
- * It's grammar is :
- *
- * <pre>
- * ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
- * requestName [0] LDAPOID,
- * requestValue [1] OCTET STRING OPTIONAL }
- * </pre>
- *
- * where 'requestName' is 1.3.6.1.1.21.1 and requestValue is absent.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class StartTransactionRequestImpl extends AbstractExtendedRequest implements StartTransactionRequest
-{
- /**
- * Creates a new instance of StartTransactionRequestImpl.
- *
- * @param messageId the message id
- */
- public StartTransactionRequestImpl( int messageId )
- {
- super( messageId );
- setRequestName( EXTENSION_OID );
- }
-
-
- /**
- * Creates a new instance of StartTransactionRequestImpl.
- */
- public StartTransactionRequestImpl()
- {
- setRequestName( EXTENSION_OID );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public StartTransactionResponse getResultResponse()
- {
- if ( getResponse() == null )
- {
- setResponse( new StartTransactionResponseImpl() );
- }
-
- return ( StartTransactionResponse ) getResponse();
- }
-}
-</code></pre>
-<p>We just implement the method that returns the associated response.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.AbstractExtendedRequest</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Implement the extended Start Transaction Request as described in RFC 5805.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * It's grammar is :
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * <pre>
+</span><span style="color:#080;font-style:italic"> * ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+</span><span style="color:#080;font-style:italic"> * requestName [0] LDAPOID,
+</span><span style="color:#080;font-style:italic"> * requestValue [1] OCTET STRING OPTIONAL }
+</span><span style="color:#080;font-style:italic"> * </pre>
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * where 'requestName' is 1.3.6.1.1.21.1 and requestValue is absent.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">StartTransactionRequestImpl</span> <span style="color:#a2f;font-weight:bold">extends</span> AbstractExtendedRequest <span style="color:#a2f;font-weight:bold">implements</span> StartTransactionRequest
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of StartTransactionRequestImpl.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param messageId the message id
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionRequestImpl</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">int</span> messageId <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> messageId <span style="color:#666">)</span><span style="color:#666">;</span>
+ setRequestName<span style="color:#666">(</span> EXTENSION_OID <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of StartTransactionRequestImpl.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionRequestImpl</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ setRequestName<span style="color:#666">(</span> EXTENSION_OID <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> StartTransactionResponse <span style="color:#00a000">getResultResponse</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getResponse<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ setResponse<span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionResponseImpl<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#666">(</span> StartTransactionResponse <span style="color:#666">)</span> getResponse<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>We just implement the method that returns the associated response.</p>
<p>Now for the response, which has an opaque value, here is the interface :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.startTransaction;
-
-
-import org.apache.directory.api.ldap.model.message.ExtendedResponse;
-
-
-/**
- * The interface for Start Transaction Extended Response. It's described in RFC 5805 :
- *
- * <pre>
- * ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
- * COMPONENTS OF LDAPResult,
- * responseName [10] LDAPOID OPTIONAL,
- * responseValue [11] OCTET STRING OPTIONAL }
- * </pre>
- *
- * where the responseName is not present, and the responseValue contain
- * a transaction identifier when the result is SUCCESS.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public interface StartTransactionResponse extends ExtendedResponse
-{
- /** The OID for the Start Transaction extended operation response. */
- String EXTENSION_OID = StartTransactionRequest.EXTENSION_OID;
-
-
- /**
- * @return The transaction ID if success
- */
- byte[] getTransactionId();
-}
-</code></pre>
-<p>As the response value is opaque, we return it as a <em>byte[]</em>.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.ExtendedResponse</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * The interface for Start Transaction Extended Response. It's described in RFC 5805 :
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * <pre>
+</span><span style="color:#080;font-style:italic"> * ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+</span><span style="color:#080;font-style:italic"> * COMPONENTS OF LDAPResult,
+</span><span style="color:#080;font-style:italic"> * responseName [10] LDAPOID OPTIONAL,
+</span><span style="color:#080;font-style:italic"> * responseValue [11] OCTET STRING OPTIONAL }
+</span><span style="color:#080;font-style:italic"> * </pre>
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * where the responseName is not present, and the responseValue contain
+</span><span style="color:#080;font-style:italic"> * a transaction identifier when the result is SUCCESS.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">interface</span> <span style="color:#00f">StartTransactionResponse</span> <span style="color:#a2f;font-weight:bold">extends</span> ExtendedResponse
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The OID for the Start Transaction extended operation response. */</span>
+ String EXTENSION_OID <span style="color:#666">=</span> StartTransactionRequest<span style="color:#666">.</span><span style="color:#b44">EXTENSION_OID</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * @return The transaction ID if success
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#00a000">getTransactionId</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>As the response value is opaque, we return it as a <em>byte[]</em>.</p>
<p>Here is the implementation :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.startTransaction;
-
-
-import org.apache.directory.api.i18n.I18n;
-import org.apache.directory.api.ldap.model.message.ExtendedResponseImpl;
-import org.apache.directory.api.ldap.model.message.ResultCodeEnum;
-import org.apache.directory.api.util.Strings;
-
-
-/**
- * The interface for Start Transaction Extended Response. It's described in RFC 5805 :
- *
- * <pre>
- * ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
- * COMPONENTS OF LDAPResult,
- * responseName [10] LDAPOID OPTIONAL,
- * responseValue [11] OCTET STRING OPTIONAL }
- * </pre>
- *
- * where the responseName is not present, and the responseValue contain
- * a transaction identifier when the result is SUCCESS.
- *
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class StartTransactionResponseImpl extends ExtendedResponseImpl implements StartTransactionResponse
-{
- /** The transaction ID if the request was successful */
- private byte[] transactionId;
-
- /**
- * Create a new StartTransactionResponseImpl object
- *
- * @param messageId The messageId
- * @param rcode the result code
- * @param transactionId The transaction ID
- */
- public StartTransactionResponseImpl( int messageId, ResultCodeEnum resultCode, byte[] transactionId )
- {
- super( messageId );
-
- switch ( resultCode )
- {
- case SUCCESS:
- this.transactionId = Strings.copy( transactionId );
- // pass through ...
- case CANCELED:
- case CANNOT_CANCEL:
- case NO_SUCH_OPERATION:
- case TOO_LATE:
- break;
-
- default:
- throw new IllegalArgumentException( I18n.err( I18n.ERR_04166, ResultCodeEnum.SUCCESS,
- ResultCodeEnum.OPERATIONS_ERROR, ResultCodeEnum.INSUFFICIENT_ACCESS_RIGHTS ) );
- }
-
- super.getLdapResult().setMatchedDn( null );
- super.getLdapResult().setResultCode( resultCode );
- }
-
-
- /**
- * Create a new StartTransactionResponseImpl instance
- *
- * @param messageId The request's messageId
- * @param transactionId The transaction ID
- */
- public StartTransactionResponseImpl( int messageId, byte[] transactionId )
- {
- super( messageId );
- super.getLdapResult().setMatchedDn( null );
- super.getLdapResult().setResultCode( ResultCodeEnum.SUCCESS );
- this.transactionId = Strings.copy( transactionId );
- }
-
-
- /**
- * Create a new StartTransactionResponseImpl instance
- *
- * @param transactionId The transaction ID
- */
- public StartTransactionResponseImpl( byte[] transactionId )
- {
- super( StartTransactionRequest.EXTENSION_OID );
- super.getLdapResult().setMatchedDn( null );
- super.getLdapResult().setResultCode( ResultCodeEnum.SUCCESS );
- this.transactionId = Strings.copy( transactionId );
- }
-
-
- /**
- * Create a new StartTransactionResponseImpl instance
- */
- public StartTransactionResponseImpl()
- {
- super( StartTransactionRequest.EXTENSION_OID );
- super.getLdapResult().setMatchedDn( null );
- super.getLdapResult().setResultCode( ResultCodeEnum.UNWILLING_TO_PERFORM );
- }
-
-
- /**
- * Gets the OID uniquely identifying this extended response (a.k.a. its
- * name). It's a null value for the Cancel response
- *
- * @return the OID of the extended response type.
- */
- @Override
- public String getResponseName()
- {
- return "";
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public int hashCode()
- {
- int hash = 37;
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.i18n.I18n</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.ExtendedResponseImpl</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.ResultCodeEnum</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.util.Strings</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * The interface for Start Transaction Extended Response. It's described in RFC 5805 :
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * <pre>
+</span><span style="color:#080;font-style:italic"> * ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+</span><span style="color:#080;font-style:italic"> * COMPONENTS OF LDAPResult,
+</span><span style="color:#080;font-style:italic"> * responseName [10] LDAPOID OPTIONAL,
+</span><span style="color:#080;font-style:italic"> * responseValue [11] OCTET STRING OPTIONAL }
+</span><span style="color:#080;font-style:italic"> * </pre>
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * where the responseName is not present, and the responseValue contain
+</span><span style="color:#080;font-style:italic"> * a transaction identifier when the result is SUCCESS.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">StartTransactionResponseImpl</span> <span style="color:#a2f;font-weight:bold">extends</span> ExtendedResponseImpl <span style="color:#a2f;font-weight:bold">implements</span> StartTransactionResponse
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The transaction ID if the request was successful */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> transactionId<span style="color:#666">;</span>
- if ( transactionId != null )
- {
- for ( byte b : transactionId )
- {
- hash += hash * 17 + b;
- }
- }
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Create a new StartTransactionResponseImpl object
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param messageId The messageId
+</span><span style="color:#080;font-style:italic"> * @param rcode the result code
+</span><span style="color:#080;font-style:italic"> * @param transactionId The transaction ID
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionResponseImpl</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">int</span> messageId<span style="color:#666">,</span> ResultCodeEnum resultCode<span style="color:#666">,</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> transactionId <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> messageId <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">switch</span> <span style="color:#666">(</span> resultCode <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">case</span> SUCCESS<span style="color:#666">:</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">transactionId</span> <span style="color:#666">=</span> Strings<span style="color:#666">.</span><span style="color:#b44">copy</span><span style="color:#666">(</span> transactionId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#080;font-style:italic">// pass through ...
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#a2f;font-weight:bold">case</span> CANCELED<span style="color:#666">:</span>
+ <span style="color:#a2f;font-weight:bold">case</span> CANNOT_CANCEL<span style="color:#666">:</span>
+ <span style="color:#a2f;font-weight:bold">case</span> NO_SUCH_OPERATION<span style="color:#666">:</span>
+ <span style="color:#a2f;font-weight:bold">case</span> TOO_LATE<span style="color:#666">:</span>
+ <span style="color:#a2f;font-weight:bold">break</span><span style="color:#666">;</span>
+<span style="color:#a0a000">
+</span><span style="color:#a0a000"> default:</span>
+ <span style="color:#a2f;font-weight:bold">throw</span> <span style="color:#a2f;font-weight:bold">new</span> IllegalArgumentException<span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">err</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">ERR_04166</span><span style="color:#666">,</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span><s [...]
+ ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">OPERATIONS_ERROR</span><span style="color:#666">,</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">INSUFFICIENT_ACCESS_RIGHTS</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setMatchedDn</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setResultCode</span><span style="color:#666">(</span> resultCode <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Create a new StartTransactionResponseImpl instance
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param messageId The request's messageId
+</span><span style="color:#080;font-style:italic"> * @param transactionId The transaction ID
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionResponseImpl</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">int</span> messageId<span style="color:#666">,</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> transactionId <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> messageId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setMatchedDn</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setResultCode</span><span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">transactionId</span> <span style="color:#666">=</span> Strings<span style="color:#666">.</span><span style="color:#b44">copy</span><span style="color:#666">(</span> transactionId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Create a new StartTransactionResponseImpl instance
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param transactionId The transaction ID
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionResponseImpl</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> transactionId <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> StartTransactionRequest<span style="color:#666">.</span><span style="color:#b44">EXTENSION_OID</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setMatchedDn</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setResultCode</span><span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">transactionId</span> <span style="color:#666">=</span> Strings<span style="color:#666">.</span><span style="color:#b44">copy</span><span style="color:#666">(</span> transactionId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Create a new StartTransactionResponseImpl instance
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionResponseImpl</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> StartTransactionRequest<span style="color:#666">.</span><span style="color:#b44">EXTENSION_OID</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setMatchedDn</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setResultCode</span><span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">UNWILLING_TO_PERFORM</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Gets the OID uniquely identifying this extended response (a.k.a. its
+</span><span style="color:#080;font-style:italic"> * name). It's a null value for the Cancel response
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @return the OID of the extended response type.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> String <span style="color:#00a000">getResponseName</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#b44">""</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">hashCode</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> hash <span style="color:#666">=</span> 37<span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> transactionId <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">for</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span> b <span style="color:#666">:</span> transactionId <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ hash <span style="color:#666">+</span><span style="color:#666">=</span> hash <span style="color:#666">*</span> 17 <span style="color:#666">+</span> b<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+
+ hash <span style="color:#666">=</span> hash <span style="color:#666">*</span> 17 <span style="color:#666">+</span> getClass<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getName</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">hashCode</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="c [...]
+
+ <span style="color:#a2f;font-weight:bold">return</span> hash<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * @see Object#equals(Object)
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">boolean</span> <span style="color:#00a000">equals</span><span style="color:#666">(</span> Object obj <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> obj <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">this</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">true</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> <span style="color:#666">!</span><span style="color:#666">(</span> obj <span style="color:#a2f;font-weight:bold">instanceof</span> StartTransactionResponseImpl <span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">false</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> Arrays<span style="color:#666">.</span><span style="color:#b44">equals</span><span style="color:#666">(</span> transactionId<span style="color:#666">,</span> <span style="color:#666">(</span> <span style="color:#666">(</span> StartTransactionResponseImpl <span style="color:#666">)</span> obj <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">transactionId</span> <span style="color: [...]
+ <span style="color:#666">}</span>
- hash = hash * 17 + getClass().getName().hashCode();
-
- return hash;
- }
-
-
- /**
- * @see Object#equals(Object)
- */
- @Override
- public boolean equals( Object obj )
- {
- if ( obj == this )
- {
- return true;
- }
-
- if ( !( obj instanceof StartTransactionResponseImpl ) )
- {
- return false;
- }
- return Arrays.equals( transactionId, ( ( StartTransactionResponseImpl ) obj ).transactionId );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public byte[] getTransactionId()
- {
- return Strings.copy( transactionId );
- }
-
-
- /**
- * {@inheritDoc}
- */
- public void setTransactionId( byte[] transactionId )
- {
- this.transactionId = Strings.copy( transactionId );
- }
-}
-</code></pre>
-<p>There is nothing special in this implementation, we just make it so the <em>transactionId</em> bytes are copied to be sure they can’t be altered from the outside. Basically, the payload is transfered pristine into the instance.</p>
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#00a000">getTransactionId</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> Strings<span style="color:#666">.</span><span style="color:#b44">copy</span><span style="color:#666">(</span> transactionId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setTransactionId</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> transactionId <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">transactionId</span> <span style="color:#666">=</span> Strings<span style="color:#666">.</span><span style="color:#b44">copy</span><span style="color:#666">(</span> transactionId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>There is nothing special in this implementation, we just make it so the <em>transactionId</em> bytes are copied to be sure they can’t be altered from the outside. Basically, the payload is transfered pristine into the instance.</p>
<p>Now that we have the interfaces and implementations, we need to add the decorators and the factory. The factory is used to initialize the <strong>API</strong> with the list of available extended operaiton at startup, as a mean to make the <strong>API</strong> extensible. It creates request and response, and the associated decorator.</p>
<p>Here is the factory code, declared in the <em><extra-codec></em> module :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction;
-
-
-import org.apache.directory.api.asn1.DecoderException;
-import org.apache.directory.api.ldap.codec.api.ExtendedOperationFactory;
-import org.apache.directory.api.ldap.codec.api.LdapApiService;
-import org.apache.directory.api.ldap.extras.extended.cancel.CancelRequest;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequest;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequestImpl;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponse;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponseImpl;
-import org.apache.directory.api.ldap.model.message.ExtendedRequest;
-import org.apache.directory.api.ldap.model.message.ExtendedResponse;
-
-
-/**
- * An {@link ExtendedOperationFactory} for creating cancel extended request response
- * pairs.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class StartTransactionFactory implements ExtendedOperationFactory
-{
- private LdapApiService codec;
-
-
- /**
- * Creates a new instance of CancelFactory.
- *
- * @param codec The codec for this factory.
- */
- public StartTransactionFactory( LdapApiService codec )
- {
- this.codec = codec;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public String getOid()
- {
- return CancelRequest.EXTENSION_OID;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public StartTransactionResponse newResponse( byte[] encodedValue ) throws DecoderException
- {
- StartTransactionResponseDecorator response = new StartTransactionResponseDecorator( codec, new StartTransactionResponseImpl() );
- response.setResponseValue( encodedValue );
-
- return response;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public StartTransactionRequest newRequest( byte[] value )
- {
- return new StartTransactionRequestDecorator( codec, new StartTransactionRequestImpl() );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public StartTransactionRequestDecorator decorate( ExtendedRequest modelRequest )
- {
- if ( modelRequest instanceof StartTransactionRequestDecorator )
- {
- return ( StartTransactionRequestDecorator ) modelRequest;
- }
-
- return new StartTransactionRequestDecorator( codec, null );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public StartTransactionResponseDecorator decorate( ExtendedResponse decoratedMessage )
- {
- if ( decoratedMessage instanceof StartTransactionResponseDecorator )
- {
- return ( StartTransactionResponseDecorator ) decoratedMessage;
- }
-
- return new StartTransactionResponseDecorator( codec, null );
- }
-}
-</code></pre>
-<p>The decorator are very simple : they just encapsulate the requets or response instance. It’s because encoding or decoding is non existant for this operation. Decorators are declared in the <em><extra-codec></em> module.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.asn1.DecoderException</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.codec.api.ExtendedOperationFactory</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.codec.api.LdapApiService</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.cancel.CancelRequest</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequest</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequestImpl</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponse</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponseImpl</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.ExtendedRequest</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.model.message.ExtendedResponse</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * An {@link ExtendedOperationFactory} for creating cancel extended request response
+</span><span style="color:#080;font-style:italic"> * pairs.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">StartTransactionFactory</span> <span style="color:#a2f;font-weight:bold">implements</span> ExtendedOperationFactory
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">private</span> LdapApiService codec<span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of CancelFactory.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param codec The codec for this factory.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionFactory</span><span style="color:#666">(</span> LdapApiService codec <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">codec</span> <span style="color:#666">=</span> codec<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> String <span style="color:#00a000">getOid</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> CancelRequest<span style="color:#666">.</span><span style="color:#b44">EXTENSION_OID</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> StartTransactionResponse <span style="color:#00a000">newResponse</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> encodedValue <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> DecoderException
+ <span style="color:#666">{</span>
+ StartTransactionResponseDecorator response <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionResponseDecorator<span style="color:#666">(</span> codec<span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionResponseImpl<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ response<span style="color:#666">.</span><span style="color:#b44">setResponseValue</span><span style="color:#666">(</span> encodedValue <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> response<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> StartTransactionRequest <span style="color:#00a000">newRequest</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> value <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionRequestDecorator<span style="color:#666">(</span> codec<span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionRequestImpl<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> StartTransactionRequestDecorator <span style="color:#00a000">decorate</span><span style="color:#666">(</span> ExtendedRequest modelRequest <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> modelRequest <span style="color:#a2f;font-weight:bold">instanceof</span> StartTransactionRequestDecorator <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#666">(</span> StartTransactionRequestDecorator <span style="color:#666">)</span> modelRequest<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionRequestDecorator<span style="color:#666">(</span> codec<span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> StartTransactionResponseDecorator <span style="color:#00a000">decorate</span><span style="color:#666">(</span> ExtendedResponse decoratedMessage <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> decoratedMessage <span style="color:#a2f;font-weight:bold">instanceof</span> StartTransactionResponseDecorator <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#666">(</span> StartTransactionResponseDecorator <span style="color:#666">)</span> decoratedMessage<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionResponseDecorator<span style="color:#666">(</span> codec<span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>The decorator are very simple : they just encapsulate the requets or response instance. It’s because encoding or decoding is non existant for this operation. Decorators are declared in the <em><extra-codec></em> module.</p>
<p>Here is teh code for both those decorators :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction;
-
-
-import org.apache.directory.api.ldap.codec.api.ExtendedRequestDecorator;
-import org.apache.directory.api.ldap.codec.api.LdapApiService;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequest;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponse;
-
-
-/**
- * A Decorator for startTransaction request.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class StartTransactionRequestDecorator extends ExtendedRequestDecorator<StartTransactionRequest> implements
- StartTransactionRequest
-{
- /** The internal startTransaction request */
- private StartTransactionRequest startTransactionRequest;
-
-
- /**
- * Creates a new instance of StartTransactionRequestDecorator.
- *
- * @param codec The LDAP Service to use
- * @param decoratedMessage The canceled request
- */
- public StartTransactionRequestDecorator( LdapApiService codec, StartTransactionRequest decoratedMessage )
- {
- super( codec, decoratedMessage );
- startTransactionRequest = decoratedMessage;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public StartTransactionResponse getResultResponse()
- {
- return ( StartTransactionResponse ) startTransactionRequest.getResultResponse();
- }
-}
-</code></pre>
-<p>and for the response :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction;
-
-
-import org.apache.directory.api.ldap.codec.api.ExtendedResponseDecorator;
-import org.apache.directory.api.ldap.codec.api.LdapApiService;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponse;
-import org.apache.directory.api.util.Strings;
-
-
-/**
- * A Decorator for CancelResponses.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class StartTransactionResponseDecorator extends ExtendedResponseDecorator<StartTransactionResponse> implements StartTransactionResponse
-{
- /** The startTransaction response */
- private StartTransactionResponse startTransactionResponse;
-
- /**
- * Creates a new instance of CancelResponseDecorator.
- *
- * @param codec The LDAP service instance
- * @param decoratedMessage The decorated message
- */
- public StartTransactionResponseDecorator( LdapApiService codec, StartTransactionResponse decoratedMessage )
- {
- super( codec, decoratedMessage );
- startTransactionResponse = decoratedMessage;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setResponseValue( byte[] responseValue )
- {
- this.responseValue = Strings.copy( responseValue );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public byte[] getTransactionId()
- {
- return startTransactionResponse.getTransactionId();
- }
-}
-</code></pre>
-<p>The last step is to declare the extended operation in the <strong>LDAP API</strong> initialization and <strong>OSGi</strong>. There are two places we have to declare the factory :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.codec.api.ExtendedRequestDecorator</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.codec.api.LdapApiService</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequest</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponse</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * A Decorator for startTransaction request.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">StartTransactionRequestDecorator</span> <span style="color:#a2f;font-weight:bold">extends</span> ExtendedRequestDecorator<span style="color:#666"><</span>StartTransactionRequest<span style="color:#666">></span> <span style="color:#a2f;font-weight:bold">implements</span>
+ StartTransactionRequest
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The internal startTransaction request */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> StartTransactionRequest startTransactionRequest<span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of StartTransactionRequestDecorator.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param codec The LDAP Service to use
+</span><span style="color:#080;font-style:italic"> * @param decoratedMessage The canceled request
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionRequestDecorator</span><span style="color:#666">(</span> LdapApiService codec<span style="color:#666">,</span> StartTransactionRequest decoratedMessage <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> codec<span style="color:#666">,</span> decoratedMessage <span style="color:#666">)</span><span style="color:#666">;</span>
+ startTransactionRequest <span style="color:#666">=</span> decoratedMessage<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> StartTransactionResponse <span style="color:#00a000">getResultResponse</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#666">(</span> StartTransactionResponse <span style="color:#666">)</span> startTransactionRequest<span style="color:#666">.</span><span style="color:#b44">getResultResponse</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>and for the response :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.codec.api.ExtendedResponseDecorator</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.codec.api.LdapApiService</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionResponse</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.util.Strings</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * A Decorator for CancelResponses.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">StartTransactionResponseDecorator</span> <span style="color:#a2f;font-weight:bold">extends</span> ExtendedResponseDecorator<span style="color:#666"><</span>StartTransactionResponse<span style="color:#666">></span> <span style="color:#a2f;font-weight:bold">implements</span> StartTransactionResponse
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The startTransaction response */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> StartTransactionResponse startTransactionResponse<span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of CancelResponseDecorator.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param codec The LDAP service instance
+</span><span style="color:#080;font-style:italic"> * @param decoratedMessage The decorated message
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">StartTransactionResponseDecorator</span><span style="color:#666">(</span> LdapApiService codec<span style="color:#666">,</span> StartTransactionResponse decoratedMessage <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> codec<span style="color:#666">,</span> decoratedMessage <span style="color:#666">)</span><span style="color:#666">;</span>
+ startTransactionResponse <span style="color:#666">=</span> decoratedMessage<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setResponseValue</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> responseValue <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">responseValue</span> <span style="color:#666">=</span> Strings<span style="color:#666">.</span><span style="color:#b44">copy</span><span style="color:#666">(</span> responseValue <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#00a000">getTransactionId</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> startTransactionResponse<span style="color:#666">.</span><span style="color:#b44">getTransactionId</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>The last step is to declare the extended operation in the <strong>LDAP API</strong> initialization and <strong>OSGi</strong>. There are two places we have to declare the factory :</p>
<ul>
<li><em>CodecFactoryUtil</em> class, in the <em><ldap/codec/standalone></em> module</li>
<li><em>ExtrasBundleActivator</em> class, in the <em><ldap/extras/codec></em> module</li>
</ul>
<p>Here is the added code in the <em>CodecFactoryUtil</em> class :</p>
-<pre><code>:::Java
-...
-import org.apache.directory.api.ldap.extras.extended.ads_impl.startTls.StartTlsFactory;
-import org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction.StartTransactionFactory;
-...
-
-/**
- * A utility class for adding Codec and extended operation factories.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public final class CodecFactoryUtil
-{
- ...
- public static void loadStockExtendedOperations(
- Map<String, ExtendedOperationFactory> extendendOperationsFactories, LdapApiService apiService )
- {
- ...
-
- StartTlsFactory startTlsFactory = new StartTlsFactory( apiService );
- extendendOperationsFactories.put( startTlsFactory.getOid(), startTlsFactory );
- LOG.info( "Registered pre-bundled extended operation factory: {}", startTlsFactory.getOid() );
-
- StartTransactionFactory startTransactionFactory = new StartTransactionFactory( apiService );
- extendendOperationsFactories.put( startTransactionFactory.getOid(), startTransactionFactory );
- LOG.info( "Registered pre-bundled extended operation factory: {}", startTransactionFactory.getOid() );
- ...
- }
-}
-</code></pre>
-<p>We just need to instanciate the factory, and to add it to the map of supported extended operations.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTls.StartTlsFactory</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction.StartTransactionFactory</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * A utility class for adding Codec and extended operation factories.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">final</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">CodecFactoryUtil</span>
+ <span style="color:#666">{</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">static</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">loadStockExtendedOperations</span><span style="color:#666">(</span>
+ Map<span style="color:#666"><</span>String<span style="color:#666">,</span> ExtendedOperationFactory<span style="color:#666">></span> extendendOperationsFactories<span style="color:#666">,</span> LdapApiService apiService <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+
+ StartTlsFactory startTlsFactory <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> StartTlsFactory<span style="color:#666">(</span> apiService <span style="color:#666">)</span><span style="color:#666">;</span>
+ extendendOperationsFactories<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> startTlsFactory<span style="color:#666">.</span><span style="color:#b44">getOid</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">,</span> startTlsFactory <span style="color:#666">)</span><span style="color:#666">;</span>
+ LOG<span style="color:#666">.</span><span style="color:#b44">info</span><span style="color:#666">(</span> <span style="color:#b44">"Registered pre-bundled extended operation factory: {}"</span><span style="color:#666">,</span> startTlsFactory<span style="color:#666">.</span><span style="color:#b44">getOid</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ StartTransactionFactory startTransactionFactory <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionFactory<span style="color:#666">(</span> apiService <span style="color:#666">)</span><span style="color:#666">;</span>
+ extendendOperationsFactories<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> startTransactionFactory<span style="color:#666">.</span><span style="color:#b44">getOid</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">,</span> startTransactionFactory <span style="color:#666">)</span><span style="color:#666">;</span>
+ LOG<span style="color:#666">.</span><span style="color:#b44">info</span><span style="color:#666">(</span> <span style="color:#b44">"Registered pre-bundled extended operation factory: {}"</span><span style="color:#666">,</span> startTransactionFactory<span style="color:#666">.</span><span style="color:#b44">getOid</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>We just need to instanciate the factory, and to add it to the map of supported extended operations.</p>
<p>And the added code for the <em>ExtrasBundleActivator</em> class :</p>
-<pre><code>:::Java
-...
-import org.apache.directory.api.ldap.extras.extended.ads_impl.startTls.StartTlsFactory;
-import org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction.StartTransactionFactory;
-...
-import org.apache.directory.api.ldap.extras.extended.startTls.StartTlsRequest;
-import org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequest;
-...
-
-/**
- * A BundleActivator for the ldap codec extras extension: extra ApacheDS and
- * Apache Directory Studio specific controls and extended operations.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class ExtrasBundleActivator implements BundleActivator
-{
- ...
- /**
- * Registers all the extras extended operations present in this control pack.
- *
- * @param codec The codec service.
- */
- private void registerExtrasExtendedOps( LdapApiService codec )
- {
- // --------------------------------------------------------------------
- // Register Extended Request Factories
- // --------------------------------------------------------------------
- ...
-
- StartTlsFactory startTlsFactory = new StartTlsFactory( codec );
- codec.registerExtendedRequest( startTlsFactory );
-
- StartTransactionFactory startTransactionFactory = new StartTransactionFactory( codec );
- codec.registerExtendedRequest( startTransactionFactory );
- ...
- }
-
-
- private void unregisterExtrasExtendedOps( LdapApiService codec )
- {
- ...
- codec.unregisterExtendedRequest( StartTlsRequest.EXTENSION_OID );
- codec.unregisterExtendedRequest( StartTransactionRequest.EXTENSION_OID );
- ...
- }
-}
-</code></pre>
-<p>We also have to export the package for it to be visible when using <strong>OSGi</strong>. This is done by modifying some <em>pom.xml</em> files.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTls.StartTlsFactory</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction.StartTransactionFactory</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTls.StartTlsRequest</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.startTransaction.StartTransactionRequest</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * A BundleActivator for the ldap codec extras extension: extra ApacheDS and
+</span><span style="color:#080;font-style:italic"> * Apache Directory Studio specific controls and extended operations.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">ExtrasBundleActivator</span> <span style="color:#a2f;font-weight:bold">implements</span> BundleActivator
+ <span style="color:#666">{</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Registers all the extras extended operations present in this control pack.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param codec The codec service.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">registerExtrasExtendedOps</span><span style="color:#666">(</span> LdapApiService codec <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">// --------------------------------------------------------------------
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#080;font-style:italic">// Register Extended Request Factories
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#080;font-style:italic">// --------------------------------------------------------------------
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+
+ StartTlsFactory startTlsFactory <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> StartTlsFactory<span style="color:#666">(</span> codec <span style="color:#666">)</span><span style="color:#666">;</span>
+ codec<span style="color:#666">.</span><span style="color:#b44">registerExtendedRequest</span><span style="color:#666">(</span> startTlsFactory <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ StartTransactionFactory startTransactionFactory <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> StartTransactionFactory<span style="color:#666">(</span> codec <span style="color:#666">)</span><span style="color:#666">;</span>
+ codec<span style="color:#666">.</span><span style="color:#b44">registerExtendedRequest</span><span style="color:#666">(</span> startTransactionFactory <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">unregisterExtrasExtendedOps</span><span style="color:#666">(</span> LdapApiService codec <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ codec<span style="color:#666">.</span><span style="color:#b44">unregisterExtendedRequest</span><span style="color:#666">(</span> StartTlsRequest<span style="color:#666">.</span><span style="color:#b44">EXTENSION_OID</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ codec<span style="color:#666">.</span><span style="color:#b44">unregisterExtendedRequest</span><span style="color:#666">(</span> StartTransactionRequest<span style="color:#666">.</span><span style="color:#b44">EXTENSION_OID</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>We also have to export the package for it to be visible when using <strong>OSGi</strong>. This is done by modifying some <em>pom.xml</em> files.</p>
<p><em><ldap/extras/codec></em> module <em>pom.xml</em> file :</p>
-<pre><code>:::XML
-...
-<configuration>
- <manifestLocation>META-INF</manifestLocation>
- <instructions>
- <Bundle-SymbolicName>${project.groupId}.ldap.extras.codec</Bundle-SymbolicName>
- <Export-Package>
- {local-packages};version=${project.version};-noimport:=true
- </Export-Package>
- <Export-Package>
- ...
- org.apache.directory.api.ldap.extras.extended.ads_impl.startTls;version=${project.version};-noimport:=true,
- org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction;version=${project.version};-noimport:=true,
- ...
- </Export-Package>
- <Import-Package>
- ...
- org.apache.directory.api.ldap.extras.extended.startTls;version=${project.version},
- org.apache.directory.api.ldap.extras.extended.startTransaction;version=${project.version},
- ...
- </Import-Package>
-</code></pre>
-<p><em><ldap/extras/codec-api></em> module <em>pom.xml</em> file :</p>
-<pre><code>:::XML
-...
-<configuration>
- <manifestLocation>META-INF</manifestLocation>
- <instructions>
- <Bundle-SymbolicName>${project.groupId}.ldap.extras.codec.api</Bundle-SymbolicName>
- <Export-Package>
- ...
- org.apache.directory.api.ldap.extras.extended.startTls;version=${project.version};-noimport:=true,
- org.apache.directory.api.ldap.extras.extended.startTransaction;version=${project.version};-noimport:=true,
- ...
- </Export-Package>
-</code></pre>
-<h1 id="a-more-complex-example">A more complex example</h1>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-XML" data-lang="XML"> ...
+ <span style="color:#008000;font-weight:bold"><configuration</span><span style="color:#008000;font-weight:bold">></span>
+ <span style="color:#008000;font-weight:bold"><manifestLocation</span><span style="color:#008000;font-weight:bold">></span>META-INF<span style="color:#008000;font-weight:bold"></manifestLocation></span>
+ <span style="color:#008000;font-weight:bold"><instructions</span><span style="color:#008000;font-weight:bold">></span>
+ <span style="color:#008000;font-weight:bold"><Bundle-SymbolicName</span><span style="color:#008000;font-weight:bold">></span>${project.groupId}.ldap.extras.codec<span style="color:#008000;font-weight:bold"></Bundle-SymbolicName></span>
+ <span style="color:#008000;font-weight:bold"><Export-Package</span><span style="color:#008000;font-weight:bold">></span>
+ {local-packages};version=${project.version};-noimport:=true
+ <span style="color:#008000;font-weight:bold"></Export-Package></span>
+ <span style="color:#008000;font-weight:bold"><Export-Package</span><span style="color:#008000;font-weight:bold">></span>
+ ...
+ org.apache.directory.api.ldap.extras.extended.ads_impl.startTls;version=${project.version};-noimport:=true,
+ org.apache.directory.api.ldap.extras.extended.ads_impl.startTransaction;version=${project.version};-noimport:=true,
+ ...
+ <span style="color:#008000;font-weight:bold"></Export-Package></span>
+ <span style="color:#008000;font-weight:bold"><Import-Package</span><span style="color:#008000;font-weight:bold">></span>
+ ...
+ org.apache.directory.api.ldap.extras.extended.startTls;version=${project.version},
+ org.apache.directory.api.ldap.extras.extended.startTransaction;version=${project.version},
+ ...
+ <span style="color:#008000;font-weight:bold"></Import-Package></span>
+</code></pre></div><p><em><ldap/extras/codec-api></em> module <em>pom.xml</em> file :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-XML" data-lang="XML"> ...
+ <span style="color:#008000;font-weight:bold"><configuration</span><span style="color:#008000;font-weight:bold">></span>
+ <span style="color:#008000;font-weight:bold"><manifestLocation</span><span style="color:#008000;font-weight:bold">></span>META-INF<span style="color:#008000;font-weight:bold"></manifestLocation></span>
+ <span style="color:#008000;font-weight:bold"><instructions</span><span style="color:#008000;font-weight:bold">></span>
+ <span style="color:#008000;font-weight:bold"><Bundle-SymbolicName</span><span style="color:#008000;font-weight:bold">></span>${project.groupId}.ldap.extras.codec.api<span style="color:#008000;font-weight:bold"></Bundle-SymbolicName></span>
+ <span style="color:#008000;font-weight:bold"><Export-Package</span><span style="color:#008000;font-weight:bold">></span>
+ ...
+ org.apache.directory.api.ldap.extras.extended.startTls;version=${project.version};-noimport:=true,
+ org.apache.directory.api.ldap.extras.extended.startTransaction;version=${project.version};-noimport:=true,
+ ...
+ <span style="color:#008000;font-weight:bold"></Export-Package></span>
+</code></pre></div><h1 id="a-more-complex-example">A more complex example</h1>
<p>Wealso have to add the <em>EndTransactionRequest</em> and <em>endTransactionResponse</em> extended opertions. We will focus on the response, which is more complex that the request.</p>
<p>The <em>EndTransactionResponse</em> value follows this ASN.1 description :</p>
-<pre><code>txnEndRes ::= SEQUENCE {
- messageID MessageID OPTIONAL,
- -- msgid associated with non-success resultCode
- updatesControls SEQUENCE OF updateControl SEQUENCE {
- messageID MessageID,
- -- msgid associated with controls
- controls Controls
- } OPTIONAL
-}
-</code></pre>
-<p>Here, <a href="https://tools.ietf.org/html/rfc5805">RFC 5805</a> gives some information about the semantic of this grammar :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> txnEndRes ::= SEQUENCE {
+ messageID MessageID OPTIONAL,
+ -- msgid associated with non-success resultCode
+ updatesControls SEQUENCE OF updateControl SEQUENCE {
+ messageID MessageID,
+ -- msgid associated with controls
+ controls Controls
+ } OPTIONAL
+ }
+</code></pre></div><p>Here, <a href="https://tools.ietf.org/html/rfc5805">RFC 5805</a> gives some information about the semantic of this grammar :</p>
<ul>
<li>we can either have a message ID, if the transaction was a failure</li>
<li>or have a list of <em>UpdateControls</em> structure if we have had a success, with some controls having to be returned</li>
<li>or we simply have nothing and then the full value is simply absent.</li>
</ul>
<p><em>Controls</em> is a list of <em>Control</em> as defined in <a href="https://tools.ietf.org/html/rfc4511#section-4.1.11">RFC 4511</a>, with the following ASN.1 description :</p>
-<pre><code>Controls ::= SEQUENCE OF control Control
-
-Control ::= SEQUENCE {
- controlType LDAPOID,
- criticality BOOLEAN DEFAULT FALSE,
- controlValue OCTET STRING OPTIONAL }
-</code></pre>
-<p>So we may have many <em>updateControls</em> and for each one of them, one to many <em>controls</em>. We will need to define a state machine to decode those two ASN/1 description.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> Controls ::= SEQUENCE OF control Control
+
+ Control ::= SEQUENCE {
+ controlType LDAPOID,
+ criticality BOOLEAN DEFAULT FALSE,
+ controlValue OCTET STRING OPTIONAL }
+</code></pre></div><p>So we may have many <em>updateControls</em> and for each one of them, one to many <em>controls</em>. We will need to define a state machine to decode those two ASN/1 description.</p>
<p>First, let’s see what is the state machine for the <em>txnEndRes</em> type and the <em>controls</em> type :</p>
<p><img src="images/EndTransactionResponse.png" alt="Extended Operations state machine"></p>
<p>The transitions from one step to the other is based on the BER encoded tag :</p>
@@ -1046,93 +1011,91 @@ Control ::= SEQUENCE {
</ul>
<p>We can see we don’t have any state associated with the <em>Control</em> decoding : it’s handled by another codec.</p>
<p>Here is the <em>enum</em> :</p>
-<pre><code>:::Java
-package org.apache.directory.api.ldap.extras.extended.ads_impl.endTransaction;
-
-
-import org.apache.directory.api.asn1.ber.grammar.States;
-
-
-/**
- * This class store the EndTransactionResponse's grammar constants. It is also used
- * for debugging purposes.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public enum EndTransactionResponseStatesEnum implements States
-{
- /** The END_STATE */
- END_STATE,
-
- /** start state*/
- START_STATE,
-
- /** The initial SEQUENCE */
- END_TRANSACTION_SEQUENCE_STATE,
-
- /** The failed message ID */
- FAILED_MESSAGE_ID_STATE,
-
- /** The update controls SEQ */
- UPDATE_CONTROLS_SEQ_STATE,
-
- /** The update control SEQ */
- UPDATE_CONTROL_SEQ_STATE,
-
- /** THe control's message ID state */
- CONTROL_MESSAGE_ID_STATE,
-
- /** The control's state */
- CONTROLS_STATE,
-
- /** Last state */
- LAST_STATE;
-
-
- /**
- * Get the grammar name
- *
- * @return The grammar name
- */
- public String getGrammarName()
- {
- return "END_TRANSACTION_RESPONSE_GRAMMER";
- }
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">package</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.ldap.extras.extended.ads_impl.endTransaction</span><span style="color:#666">;</span>
- /**
- * Get the string representing the state
- *
- * @param state The state number
- * @return The String representing the state
- */
- public String getState( int state )
- {
- return ( state == END_STATE.ordinal() ) ? "END_TRANSACTION_RESPONSE_GRAMMER" : name();
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public boolean isEndState()
- {
- return this == END_STATE;
- }
+ <span style="color:#a2f;font-weight:bold">import</span> <span style="color:#00f;font-weight:bold">org.apache.directory.api.asn1.ber.grammar.States</span><span style="color:#666">;</span>
- /**
- * {@inheritDoc}
- */
- @Override
- public EndTransactionResponseStatesEnum getStartState()
- {
- return START_STATE;
- }
-}
-</code></pre>
-<p>We can now define transitions between states, accordingly to the grammar semantic :</p>
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * This class store the EndTransactionResponse's grammar constants. It is also used
+</span><span style="color:#080;font-style:italic"> * for debugging purposes.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">enum</span> EndTransactionResponseStatesEnum <span style="color:#a2f;font-weight:bold">implements</span> States
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The END_STATE */</span>
+ END_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** start state*/</span>
+ START_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** The initial SEQUENCE */</span>
+ END_TRANSACTION_SEQUENCE_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** The failed message ID */</span>
+ FAILED_MESSAGE_ID_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** The update controls SEQ */</span>
+ UPDATE_CONTROLS_SEQ_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** The update control SEQ */</span>
+ UPDATE_CONTROL_SEQ_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** THe control's message ID state */</span>
+ CONTROL_MESSAGE_ID_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** The control's state */</span>
+ CONTROLS_STATE<span style="color:#666">,</span>
+
+ <span style="color:#080;font-style:italic">/** Last state */</span>
+ LAST_STATE<span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Get the grammar name
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @return The grammar name
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> String <span style="color:#00a000">getGrammarName</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#b44">"END_TRANSACTION_RESPONSE_GRAMMER"</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Get the string representing the state
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param state The state number
+</span><span style="color:#080;font-style:italic"> * @return The String representing the state
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> String <span style="color:#00a000">getState</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">int</span> state <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#666">(</span> state <span style="color:#666">=</span><span style="color:#666">=</span> END_STATE<span style="color:#666">.</span><span style="color:#b44">ordinal</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span> <span style="color:#666">?</span> <span style="color:#b44">"END_TRANSACTION_RESPONSE_GRAMMER"</span> <span style="color:#666">: [...]
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">boolean</span> <span style="color:#00a000">isEndState</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">this</span> <span style="color:#666">=</span><span style="color:#666">=</span> END_STATE<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> EndTransactionResponseStatesEnum <span style="color:#00a000">getStartState</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> START_STATE<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>We can now define transitions between states, accordingly to the grammar semantic :</p>
<table>
<thead>
<tr>
@@ -1218,52 +1181,50 @@ public enum EndTransactionResponseStatesEnum implements States
</ul>
<p>Each state may have many transitions going to many different states, but each transition must use a different tag.</p>
<p>Here is an example of transition :</p>
-<pre><code>:::Java
-/**
- * Transition from Sequence to messageId
- *
- * txnEndReq ::= SEQUENCE {
- * messageID MessageID OPTIONAL,
- * -- msgid associated with non-success resultCode
- * ...
- *
- * Set the messageId into the EndTransactionResponse instance, if it's not SUCCESS.
- */
-super.transitions[EndTransactionResponseStatesEnum.END_TRANSACTION_SEQUENCE_STATE.ordinal()][UniversalTag.INTEGER.getValue()] =
- new GrammarTransition<EndTransactionResponseContainer>(
- EndTransactionResponseStatesEnum.END_TRANSACTION_SEQUENCE_STATE,
- EndTransactionResponseStatesEnum.FAILED_MESSAGE_ID_STATE,
- UniversalTag.INTEGER.getValue(),
- new GrammarAction<EndTransactionResponseContainer>( "Set EndTransactionResponse failed MessageID" )
- {
- public void action( EndTransactionResponseContainer container ) throws DecoderException
- {
- BerValue value = container.getCurrentTLV().getValue();
-
- try
- {
- int failedMessageId = IntegerDecoder.parse( value );
-
- if ( failedMessageId > 0 )
- {
- container.getEndTransactionResponse().setFailedMessageId( failedMessageId );
- }
-
- // We may have nothing left
- container.setGrammarEndAllowed( true );
- }
- catch ( IntegerDecoderException ide )
- {
- LOG.error( I18n
- .err( I18n.ERR_04490_BAD_END_TRANSACTION_COMMIT, Strings.dumpBytes( value.getData() ), ide.getMessage() ) );
-
- // This will generate a PROTOCOL_ERROR
- throw new DecoderException( ide.getMessage(), ide );
- }
- }
- } );
-</code></pre>
-<p>In this example, we have a transition from a <strong>END_TRANSACTION_SEQUENCE_STATE</strong> state to a <strong>FAILED_MESSAGE_ID</strong> state, which is triggered by an <strong>INTEGER</strong> tag. The executed action is created immediately, but it could have been a separated class.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Transition from Sequence to messageId
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * txnEndReq ::= SEQUENCE {
+</span><span style="color:#080;font-style:italic"> * messageID MessageID OPTIONAL,
+</span><span style="color:#080;font-style:italic"> * -- msgid associated with non-success resultCode
+</span><span style="color:#080;font-style:italic"> * ...
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * Set the messageId into the EndTransactionResponse instance, if it's not SUCCESS.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">transitions</span><span style="color:#666">[</span>EndTransactionResponseStatesEnum<span style="color:#666">.</span><span style="color:#b44">END_TRANSACTION_SEQUENCE_STATE</span><span style="color:#666">.</span><span style="color:#b44">ordinal</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">]</span><span style="color:#666">[< [...]
+ <span style="color:#a2f;font-weight:bold">new</span> GrammarTransition<span style="color:#666"><</span>EndTransactionResponseContainer<span style="color:#666">></span><span style="color:#666">(</span>
+ EndTransactionResponseStatesEnum<span style="color:#666">.</span><span style="color:#b44">END_TRANSACTION_SEQUENCE_STATE</span><span style="color:#666">,</span>
+ EndTransactionResponseStatesEnum<span style="color:#666">.</span><span style="color:#b44">FAILED_MESSAGE_ID_STATE</span><span style="color:#666">,</span>
+ UniversalTag<span style="color:#666">.</span><span style="color:#b44">INTEGER</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">,</span>
+ <span style="color:#a2f;font-weight:bold">new</span> GrammarAction<span style="color:#666"><</span>EndTransactionResponseContainer<span style="color:#666">></span><span style="color:#666">(</span> <span style="color:#b44">"Set EndTransactionResponse failed MessageID"</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">action</span><span style="color:#666">(</span> EndTransactionResponseContainer container <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> DecoderException
+ <span style="color:#666">{</span>
+ BerValue value <span style="color:#666">=</span> container<span style="color:#666">.</span><span style="color:#b44">getCurrentTLV</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> failedMessageId <span style="color:#666">=</span> IntegerDecoder<span style="color:#666">.</span><span style="color:#b44">parse</span><span style="color:#666">(</span> value <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> failedMessageId <span style="color:#666">></span> 0 <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ container<span style="color:#666">.</span><span style="color:#b44">getEndTransactionResponse</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setFailedMessageId</span><span style="color:#666">(</span> failedMessageId <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#080;font-style:italic">// We may have nothing left
+</span><span style="color:#080;font-style:italic"></span> container<span style="color:#666">.</span><span style="color:#b44">setGrammarEndAllowed</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">true</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> IntegerDecoderException ide <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ LOG<span style="color:#666">.</span><span style="color:#b44">error</span><span style="color:#666">(</span> I18n
+ <span style="color:#666">.</span><span style="color:#b44">err</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">ERR_04490_BAD_END_TRANSACTION_COMMIT</span><span style="color:#666">,</span> Strings<span style="color:#666">.</span><span style="color:#b44">dumpBytes</span><span style="color:#666">(</span> value<span style="color:#666">.</span><span style="color:#b44">getData</span><span style="color:#666">(</spa [...]
+
+ <span style="color:#080;font-style:italic">// This will generate a PROTOCOL_ERROR
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#a2f;font-weight:bold">throw</span> <span style="color:#a2f;font-weight:bold">new</span> DecoderException<span style="color:#666">(</span> ide<span style="color:#666">.</span><span style="color:#b44">getMessage</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">,</span> ide <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>In this example, we have a transition from a <strong>END_TRANSACTION_SEQUENCE_STATE</strong> state to a <strong>FAILED_MESSAGE_ID</strong> state, which is triggered by an <strong>INTEGER</strong> tag. The executed action is created immediately, but it could have been a separated class.</p>
diff --git a/content/api/internal-design-guide/3-building.html b/content/api/internal-design-guide/3-building.html
index 229e58e..50168a0 100644
--- a/content/api/internal-design-guide/3-building.html
+++ b/content/api/internal-design-guide/3-building.html
@@ -159,29 +159,27 @@
<h1 id="3---building">3 - Building</h1>
<p>The project is based on <strong>Apache Maven</strong> (version 3.x), so you’ll have to install it first.</p>
<p>That being said, building the <strong>LDAP API</strong> is pretty straightforward :</p>
-<pre><code>:::
-$ mvn clean install
-Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Reactor Build Order:
-[INFO]
-[INFO] Apache Directory LDAP API
-[INFO] Apache Directory LDAP API I18n
-[INFO] Apache Directory LDAP API Utilities
-...
-[INFO] Apache Directory LDAP API Model
-[INFO] Apache Directory LDAP API Codec Parent
-[INFO] Apache Directory API Integration Tests
-[INFO] Apache Directory API OSGi Integration Tests
-[INFO] Apache Directory LDAP API Distribution
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] Building Apache Directory LDAP API 2.0.0.AM1-SNAPSHOT
-[INFO] ------------------------------------------------------------------------
-...
-</code></pre>
-<p>It takes around 1 min to build it all (a bit longer the first time, as some dependencies wil have to be pulled from the net).</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> $ mvn clean install
+ Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0
+ [INFO] Scanning for projects...
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Reactor Build Order:
+ [INFO]
+ [INFO] Apache Directory LDAP API
+ [INFO] Apache Directory LDAP API I18n
+ [INFO] Apache Directory LDAP API Utilities
+ ...
+ [INFO] Apache Directory LDAP API Model
+ [INFO] Apache Directory LDAP API Codec Parent
+ [INFO] Apache Directory API Integration Tests
+ [INFO] Apache Directory API OSGi Integration Tests
+ [INFO] Apache Directory LDAP API Distribution
+ [INFO]
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building Apache Directory LDAP API 2.0.0.AM1-SNAPSHOT
+ [INFO] ------------------------------------------------------------------------
+ ...
+</code></pre></div><p>It takes around 1 min to build it all (a bit longer the first time, as some dependencies wil have to be pulled from the net).</p>
<p>The top level <em>pom.xml</em> depends on teh special <em>project</em> ‘project’, which is used by all the <strong>ApacheDS</strong> projects. It gathers information about maven plugin dependenies and someother things. You don’t really need to touch it anyway…</p>
<p>Remember to use <strong>Java 8</strong> !!</p>
diff --git a/content/api/internal-design-guide/4-asn1.html b/content/api/internal-design-guide/4-asn1.html
index 24c7d5f..c71cb46 100644
--- a/content/api/internal-design-guide/4-asn1.html
+++ b/content/api/internal-design-guide/4-asn1.html
@@ -170,10 +170,8 @@
<p>An encoded ASN/1 message is a tuple contianing two or three elements : a <strong>T</strong>ype, a <strong>L</strong>ength and optionally - ie if the length is not 0 - a <strong>V</strong>alue. This tuple is called a <strong>TLV</strong>. Every message is a <strong>TLV</strong>.</p>
<p>But a message can be have complex structure, so a <strong>TLV</strong> itself can encapsulate some <strong>TLV</strong>s. Actually the <strong>V</strong> part can be a list of <strong>TLV</strong>s. This is recursive…</p>
<p>A typical encoded message can therefore represented this way :</p>
-<pre><code>:::
-[TL [TLV] [TL [TLV] [TLV]]]
-</code></pre>
-<p>Here, the message <strong>TLV</strong> value is a set of two <strong>TLV</strong>s, teh second one being itself a composition of 2 <strong>TLV</strong>s.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> [TL [TLV] [TL [TLV] [TLV]]]
+</code></pre></div><p>Here, the message <strong>TLV</strong> value is a set of two <strong>TLV</strong>s, teh second one being itself a composition of 2 <strong>TLV</strong>s.</p>
<p>The <strong>T</strong> describe the type of value, the <strong>L</strong> gives the length of this value (can be 0) and of course the <strong>V</strong> is the value, which can itself be a <strong>TLV</strong>.</p>
<h3 id="encoderdecoder">Encoder/Decoder</h3>
<p>There are two aspects we have to deal with :</p>
diff --git a/content/api/internal-design-guide/4.1-asn1-tlv.html b/content/api/internal-design-guide/4.1-asn1-tlv.html
index 336013c..6d85fe2 100644
--- a/content/api/internal-design-guide/4.1-asn1-tlv.html
+++ b/content/api/internal-design-guide/4.1-asn1-tlv.html
@@ -175,25 +175,21 @@
<li>If the label is 31, then more than one byte is used to encode the <strong>Type</strong>. In this case, we use the following bytes to compute the label, where each byte which high bit is one will be followed by another byte.</li>
</ul>
<p>We limit the label to 2,097,151 as we encode the <strong>Type</strong> in one Java int :</p>
-<pre><code>:::
-b1 xxx[1-1111], b2 1[111-1111], b3 1[111-1111], b4 0[111-1111]
-->
-[111-1111][111-1111][111-1111]
-->
-0001-1111 1111-1111 1111-1111
-->
-0x1FFFFF
-->
-2,097,151
-</code></pre>
-<p>In <strong>LDAP</strong> or <strong>Kerberos</strong>, no label is higher than 30, so we always use 1 byte <strong>Type</strong>s.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> b1 xxx[1-1111], b2 1[111-1111], b3 1[111-1111], b4 0[111-1111]
+ ->
+ [111-1111][111-1111][111-1111]
+ ->
+ 0001-1111 1111-1111 1111-1111
+ ->
+ 0x1FFFFF
+ ->
+ 2,097,151
+</code></pre></div><p>In <strong>LDAP</strong> or <strong>Kerberos</strong>, no label is higher than 30, so we always use 1 byte <strong>Type</strong>s.</p>
<p>Other interesting information that we need to grab from a <em>Type</em> are stored in the two first bits (bit 7 and 6), and in the third bit (bit 5). The first two bits describe the class, the third tells if the <strong>TLV</strong> is a <strong>primitive</strong> (b5 = 0) or a <strong>constructed</strong> <strong>TLV</strong> (b5 = 1).</p>
<h3 id="length">Length</h3>
<p><strong>Length</strong> gives the number of bytes of the <strong>Value</strong>, and nothing else. So the total length of a <strong>TLV</strong> will be:</p>
-<pre><code>:::
-TLV length = Tag length + Length length + Value length,
-</code></pre>
-<p>where the <strong>Value</strong> length is stored in the <strong>Length</strong> element.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> TLV length = Tag length + Length length + Value length,
+</code></pre></div><p>where the <strong>Value</strong> length is stored in the <strong>Length</strong> element.</p>
<p>The <strong>Length</strong> may be 0, which means that there is no value following.</p>
<p>How is <strong>Length</strong> encoded? A <strong>Value</strong> may be from 0 to N bytes long, with N < (256 ^ 126) - 1. This limit is purely hypothetic, of course. If we have to deal with huge objects like pictures or movies, their length will not exceed a few MBytes or a few GBytes</p>
<p>Typically, we will find five kind of <strong>Length</strong>s :</p>
@@ -208,33 +204,29 @@ TLV length = Tag length + Length length + Value length,
<p>The fourth type could also be ignored (4 GBytes is quite a huge size for an LDAP element …), so we can decide that we won’t accept those <strong>Values</strong>. It seems reasonable.</p>
<p>As the <strong>Length</strong> can be stored in more than one byte, we have to take care of fragmented <strong>PDU</strong> : we may receive only the first bytes, and have to wait for the rest to be received. The idea is to freeze and start again when we receive some more data.</p>
<p>In any case, if the first byte is > 0x7F, that means it’s a multi-bytes length, and we have to process the following bytesto get the real length. In this case, the first byte contains teh number of expected following bytes. Typically :</p>
-<pre><code>:::
-0x74 -> 116
-0x82 0x02 0x84 : 2 bytes, length = 2 * 16 + 132 -> 164
-0x81 0x84 : 1 byte, length = 132
-</code></pre>
-<h3 id="value">Value</h3>
-<p><strong>Value</strong> carries the ‘meat’ of a <strong>TLV</strong>. Depending on the <strong>Type</strong>, it’s either a primitive value, or a constructed one (which means it contains a <strong>TLV</strong> or a set of <strong>TLV</strong>s). Remember that bit 5 of the <strong>Type</strong> tells if the **Value is <em>primitive</em> ( b5 == 0) or _constructed (b5 == 1).</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> 0x74 -> 116
+ 0x82 0x02 0x84 : 2 bytes, length = 2 * 16 + 132 -> 164
+ 0x81 0x84 : 1 byte, length = 132
+</code></pre></div><h3 id="value">Value</h3>
+<p><strong>Value</strong> carries the ‘meat’ of a <strong>TLV</strong>. Depending on the <strong>Type</strong>, it’s either a primitive value, or a constructed one (which means it contains a <strong>TLV</strong> or a set of <strong>TLV</strong>s). Remember that bit 5 of the <strong>Type</strong> tells if the <strong>Value</strong> is <em>primitive</em> ( b5 == 0) or <em>constructed</em> (b5 == 1).</p>
<ul>
-<li>If we have a <em>primitive</em> <strong>Value</strong>, we have to read <strong>Length</strong> byte and we are done
-** If we have a <em>constructed</em> <strong>Value</strong>, we have to process it as one or more <strong>TLV</strong>.</li>
+<li>If we have a <em>primitive</em> <strong>Value</strong>, we have to read <strong>Length</strong> byte and we are done</li>
+<li>If we have a <em>constructed</em> <strong>Value</strong>, we have to process it as one or more <strong>TLV</strong>.</li>
</ul>
<h2 id="tlv-processing">TLV processing</h2>
<p>In the <strong>API</strong>, the <strong>TLV</strong> processing is done in the <em>Asn1Decoder</em> class, and more specifically by the <em>decode( ByteBuffer stream, Asn1Container container )</em> method, which takes a ByteBuffer as input, and feed a container as a result.</p>
<p>The important thing to understand is that this method can be called repetively, until a message is fully decoded, as soon as we feed it with some new <em>ByteBuffer</em>. The <em>Container</em> instance will contain the result, as soon as its state has switched to <strong>PDU_DECODED</strong>.</p>
<p>While processing a <strong>TLV</strong>, when we are done with the <strong>Value</strong> part, the decoder will check if any action is to be executed. The action is associated to the grammar in use, which is stored in the container. Here is the part that call the action, in the <em>Asn1Decoder.treatTLVDoneState()</em> method :</p>
-<pre><code>:::java
-private boolean treatTLVDoneState( ByteBuffer stream, Asn1Container container ) throws DecoderException
-{
- // First, we have to execute the associated action
- container.getGrammar().executeAction( container );
- ...
-</code></pre>
-<p>So the <em>Container</em> must contain the grammar, and the current state. We may not have any action to execute, either because none is associated with the current transition or because we are at the end of the message.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"> <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">boolean</span> <span style="color:#00a000">treatTLVDoneState</span><span style="color:#666">(</span> ByteBuffer stream<span style="color:#666">,</span> Asn1Container container <span style="color:#666">)</span> <span style="color:#a2f;font-wei [...]
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">// First, we have to execute the associated action
+</span><span style="color:#080;font-style:italic"></span> container<span style="color:#666">.</span><span style="color:#b44">getGrammar</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">executeAction</span><span style="color:#666">(</span> container <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>So the <em>Container</em> must contain the grammar, and the current state. We may not have any action to execute, either because none is associated with the current transition or because we are at the end of the message.</p>
<h3 id="tlv-implementation">TLV implementation</h3>
<p>The <strong>TLV</strong> class stores the <strong>Type</strong>, <strong>Length</strong> and <strong>Value</strong>, plus some extra information, like a unique <em>id</em>, a reference to its parent’s <strong>TLV</strong> and the expected length when the included <strong>Value</strong> is a set of <strong>TLV</strong>.</p>
<p><img src="images/tlv-bervalue.png" alt="TLV/BerValue"></p>
-<p>You won’t have tp manipulate <strong>TLV</strong> frequently, except in the actions, where you might fetch its <em>Length</em>* and **Value** content, using _getLength()_ and _getValue().getData()_ methods respectively.</p>
+<p>You won’t have tp manipulate <strong>TLV</strong> frequently, except in the actions, where you might fetch its <strong>Length</strong> and <strong>Value</strong> content, using <em>getLength()</em> and <em>getValue().getData()</em> methods respectively.</p>
<h3 id="action">Action</h3>
<p>This is quite a simple class and hierarchy :</p>
<p><img src="images/grammar-action.png" alt="GrammarAction"></p>
@@ -242,471 +234,463 @@ private boolean treatTLVDoneState( ByteBuffer stream, Asn1Container container )
<p>At this point, an example would be useful.</p>
<h2 id="example">Example</h2>
<p>Let say we want to implement a decoder for the following message :</p>
-<pre><code>:::
-EntryChangeNotification ::= SEQUENCE
-{
- changeType ENUMERATED
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> EntryChangeNotification ::= SEQUENCE
{
- add (1),
- delete (2),
- modify (4),
- modDN (8)
- },
- previousDN LDAPDN OPTIONAL, -- modifyDN ops. only
- changeNumber INTEGER OPTIONAL -- if supported
-}
-</code></pre>
-<p>You don’t need to know anything about this message, what is important is how we will decode it.</p>
+ changeType ENUMERATED
+ {
+ add (1),
+ delete (2),
+ modify (4),
+ modDN (8)
+ },
+ previousDN LDAPDN OPTIONAL, -- modifyDN ops. only
+ changeNumber INTEGER OPTIONAL -- if supported
+ }
+</code></pre></div><p>You don’t need to know anything about this message, what is important is how we will decode it.</p>
<p>The first thing we need to create is an interface and a implementation for the Java object that will represent the <strong>EntryChange</strong> object.</p>
<p>Here is the interface (note that it’s a <em>Control</em>, but it’s a irrelevant information here) :</p>
-<pre><code>:::Java
-public interface EntryChange extends Control
-{
- /** No defined change number */
- int UNDEFINED_CHANGE_NUMBER = -1;
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">interface</span> <span style="color:#00f">EntryChange</span> <span style="color:#a2f;font-weight:bold">extends</span> Control
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** No defined change number */</span>
+ <span style="color:#0b0;font-weight:bold">int</span> UNDEFINED_CHANGE_NUMBER <span style="color:#666">=</span> <span style="color:#666">-</span>1<span style="color:#666">;</span>
- /** The EntryChange control */
- String OID = "2.16.840.1.113730.3.4.7";
+ <span style="color:#080;font-style:italic">/** The EntryChange control */</span>
+ String OID <span style="color:#666">=</span> <span style="color:#b44">"2.16.840.1.113730.3.4.7"</span><span style="color:#666">;</span>
- /**
- * @return The ChangeType
- */
- ChangeType getChangeType();
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * @return The ChangeType
+</span><span style="color:#080;font-style:italic"> */</span>
+ ChangeType <span style="color:#00a000">getChangeType</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
- /**
- * Set the ChangeType
- *
- * @param changeType Add, Delete; Modify or ModifyDN
- */
- void setChangeType( ChangeType changeType );
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Set the ChangeType
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param changeType Add, Delete; Modify or ModifyDN
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setChangeType</span><span style="color:#666">(</span> ChangeType changeType <span style="color:#666">)</span><span style="color:#666">;</span>
- /**
- * @return The previous DN
- */
- Dn getPreviousDn();
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * @return The previous DN
+</span><span style="color:#080;font-style:italic"> */</span>
+ Dn <span style="color:#00a000">getPreviousDn</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
- /**
- * Sets the previous DN
- *
- * @param previousDn The previous DN
- */
- void setPreviousDn( Dn previousDn );
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Sets the previous DN
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param previousDn The previous DN
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setPreviousDn</span><span style="color:#666">(</span> Dn previousDn <span style="color:#666">)</span><span style="color:#666">;</span>
- /**
- * @return The change number
- */
- long getChangeNumber();
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * @return The change number
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#0b0;font-weight:bold">long</span> <span style="color:#00a000">getChangeNumber</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
- /**
- * Sets the ChangeNumber
- *
- * @param changeNumber The ChanegNumber
- */
- void setChangeNumber( long changeNumber );
-}
-</code></pre>
-<p>What is important is that we declare all the setters and getters for the object fields that matter : <em>changeType</em>, <em>previousDN</em> and <em>changeNumber</em></p>
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Sets the ChangeNumber
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param changeNumber The ChanegNumber
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setChangeNumber</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">long</span> changeNumber <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>What is important is that we declare all the setters and getters for the object fields that matter : <em>changeType</em>, <em>previousDN</em> and <em>changeNumber</em></p>
<p>The implementation is not really complex :</p>
-<pre><code>:::Java
-/**
- * A simple implementation of the EntryChange response control.
- *
- * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
- */
-public class EntryChangeImpl extends AbstractControl implements EntryChange
-{
- /** The changeType */
- private ChangeType changeType = ChangeType.ADD;
-
- private long changeNumber = UNDEFINED_CHANGE_NUMBER;
-
- /** The previous Dn */
- private Dn previousDn = null;
-
-
- /**
- *
- * Creates a new instance of EntryChangeControl.
- *
- */
- public EntryChangeImpl()
- {
- super( OID );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public ChangeType getChangeType()
- {
- return changeType;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setChangeType( ChangeType changeType )
- {
- this.changeType = changeType;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public Dn getPreviousDn()
- {
- return previousDn;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setPreviousDn( Dn previousDn )
- {
- this.previousDn = previousDn;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public long getChangeNumber()
- {
- return changeNumber;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setChangeNumber( long changeNumber )
- {
- this.changeNumber = changeNumber;
- }
-
-
- /**
- * @see Object#hashCode()
- */
- @Override
- public int hashCode()
- {
- int h = super.hashCode();
-
- h = h * 37 + ( int ) changeNumber;
- h = h * 37 + ( changeType == null ? 0 : changeType.hashCode() );
- h = h * 37 + ( previousDn == null ? 0 : previousDn.hashCode() );
-
- return h;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public boolean equals( Object o )
- {
- if ( !super.equals( o ) )
- {
- return false;
- }
-
- EntryChange otherControl = ( EntryChange ) o;
-
- return ( changeNumber == otherControl.getChangeNumber() ) && ( changeType == otherControl.getChangeType() )
- && ( previousDn.equals( otherControl.getPreviousDn() ) );
- }
-
-
- /**
- * Return a String representing this EntryChangeControl.
- */
- @Override
- public String toString()
- {
- StringBuilder sb = new StringBuilder();
-
- sb.append( " Entry Change Control\n" );
- sb.append( " oid : " ).append( getOid() ).append( '\n' );
- sb.append( " critical : " ).append( isCritical() ).append( '\n' );
- sb.append( " changeType : '" ).append( changeType ).append( "'\n" );
- sb.append( " previousDN : '" ).append( previousDn ).append( "'\n" );
-
- if ( changeNumber == UNDEFINED_CHANGE_NUMBER )
- {
- sb.append( " changeNumber : '" ).append( "UNDEFINED" ).append( "'\n" );
- }
- else
- {
- sb.append( " changeNumber : '" ).append( changeNumber ).append( "'\n" );
- }
-
- return sb.toString();
- }
-}
-</code></pre>
-<p>This is pretty much trivial.</p>
-<p>We now need a _Decorator to manipulate this instance. Here is the code :</p>
-<pre><code>:::Java
-public class EntryChangeDecorator extends ControlDecorator<EntryChange> implements EntryChange
-{
- /** Default value when no change number is provided */
- public static final int UNDEFINED_CHANGE_NUMBER = -1;
-
- /** A temporary storage for the previous Dn */
- private byte[] previousDnBytes = null;
-
- /** The entry change global length */
- private int eccSeqLength;
-
- /** An instance of this decoder */
- private static final Asn1Decoder DECODER = new Asn1Decoder();
-
-
- /**
- * Creates a new instance of EntryChangeDecoder wrapping a newly created
- * EntryChange Control object.
- *
- * @param codec The LDAP service instance
- */
- public EntryChangeDecorator( LdapApiService codec )
- {
- super( codec, new EntryChangeImpl() );
- }
-
-
- /**
- * Creates a new instance of EntryChangeDecorator wrapping the supplied
- * EntryChange Control.
- *
- * @param codec The LDAP service instance
- * @param control The EntryChange Control to be decorated.
- */
- public EntryChangeDecorator( LdapApiService codec, EntryChange control )
- {
- super( codec, control );
- }
-
-
- /**
- * Internally used to not have to cast the decorated Control.
- *
- * @return the decorated Control.
- */
- private EntryChange getEntryChange()
- {
- return getDecorated();
- }
-
-
- /**
- * Compute the EntryChangeControl length
- *
- * <pre>
- * 0x30 L1
- * |
- * +--&gt; 0x0A 0x0(1-4) [1|2|4|8] (changeType)
- * [+--&gt; 0x04 L2 previousDN]
- * [+--&gt; 0x02 0x0(1-4) [0..2^63-1] (changeNumber)]
- * </pre>
- *
- * @return the control length.
- */
- @Override
- public int computeLength()
- {
- int changeTypesLength = 1 + 1 + 1;
-
- int previousDnLength = 0;
- int changeNumberLength = 0;
-
- if ( getPreviousDn() != null )
- {
- previousDnBytes = Strings.getBytesUtf8( getPreviousDn().getName() );
- previousDnLength = 1 + TLV.getNbBytes( previousDnBytes.length ) + previousDnBytes.length;
- }
-
- if ( getChangeNumber() != UNDEFINED_CHANGE_NUMBER )
- {
- changeNumberLength = 1 + 1 + BerValue.getNbBytes( getChangeNumber() );
- }
-
- eccSeqLength = changeTypesLength + previousDnLength + changeNumberLength;
- valueLength = 1 + TLV.getNbBytes( eccSeqLength ) + eccSeqLength;
-
- return valueLength;
- }
-
-
- /**
- * Encodes the entry change control.
- *
- * @param buffer The encoded sink
- * @return A ByteBuffer that contains the encoded PDU
- * @throws EncoderException If anything goes wrong.
- */
- @Override
- public ByteBuffer encode( ByteBuffer buffer ) throws EncoderException
- {
- if ( buffer == null )
- {
- throw new EncoderException( I18n.err( I18n.ERR_04023 ) );
- }
-
- buffer.put( UniversalTag.SEQUENCE.getValue() );
- buffer.put( TLV.getBytes( eccSeqLength ) );
-
- buffer.put( UniversalTag.ENUMERATED.getValue() );
- buffer.put( ( byte ) 1 );
- buffer.put( BerValue.getBytes( getChangeType().getValue() ) );
-
- if ( getPreviousDn() != null )
- {
- BerValue.encode( buffer, previousDnBytes );
- }
-
- if ( getChangeNumber() != UNDEFINED_CHANGE_NUMBER )
- {
- BerValue.encode( buffer, getChangeNumber() );
- }
-
- return buffer;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public byte[] getValue()
- {
- if ( value == null )
- {
- try
- {
- computeLength();
- ByteBuffer buffer = ByteBuffer.allocate( valueLength );
-
- buffer.put( UniversalTag.SEQUENCE.getValue() );
- buffer.put( TLV.getBytes( eccSeqLength ) );
-
- buffer.put( UniversalTag.ENUMERATED.getValue() );
- buffer.put( ( byte ) 1 );
- buffer.put( BerValue.getBytes( getChangeType().getValue() ) );
-
- if ( getPreviousDn() != null )
- {
- BerValue.encode( buffer, previousDnBytes );
- }
-
- if ( getChangeNumber() != UNDEFINED_CHANGE_NUMBER )
- {
- BerValue.encode( buffer, getChangeNumber() );
- }
-
- value = buffer.array();
- }
- catch ( Exception e )
- {
- return null;
- }
- }
-
- return value;
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public ChangeType getChangeType()
- {
- return getEntryChange().getChangeType();
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setChangeType( ChangeType changeType )
- {
- getEntryChange().setChangeType( changeType );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public Dn getPreviousDn()
- {
- return getEntryChange().getPreviousDn();
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setPreviousDn( Dn previousDn )
- {
- getEntryChange().setPreviousDn( previousDn );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public long getChangeNumber()
- {
- return getEntryChange().getChangeNumber();
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public void setChangeNumber( long changeNumber )
- {
- getEntryChange().setChangeNumber( changeNumber );
- }
-
-
- /**
- * {@inheritDoc}
- */
- @Override
- public Asn1Object decode( byte[] controlBytes ) throws DecoderException
- {
- ByteBuffer bb = ByteBuffer.wrap( controlBytes );
- EntryChangeContainer container = new EntryChangeContainer( getCodecService(), this );
- DECODER.decode( bb, container );
- return this;
- }
-}
-</code></pre>
-
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * A simple implementation of the EntryChange response control.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">EntryChangeImpl</span> <span style="color:#a2f;font-weight:bold">extends</span> AbstractControl <span style="color:#a2f;font-weight:bold">implements</span> EntryChange
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** The changeType */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> ChangeType changeType <span style="color:#666">=</span> ChangeType<span style="color:#666">.</span><span style="color:#b44">ADD</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">long</span> changeNumber <span style="color:#666">=</span> UNDEFINED_CHANGE_NUMBER<span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">/** The previous Dn */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> Dn previousDn <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of EntryChangeControl.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">EntryChangeImpl</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> OID <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> ChangeType <span style="color:#00a000">getChangeType</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> changeType<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setChangeType</span><span style="color:#666">(</span> ChangeType changeType <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">changeType</span> <span style="color:#666">=</span> changeType<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> Dn <span style="color:#00a000">getPreviousDn</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> previousDn<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setPreviousDn</span><span style="color:#666">(</span> Dn previousDn <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">previousDn</span> <span style="color:#666">=</span> previousDn<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">long</span> <span style="color:#00a000">getChangeNumber</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> changeNumber<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setChangeNumber</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">long</span> changeNumber <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">.</span><span style="color:#b44">changeNumber</span> <span style="color:#666">=</span> changeNumber<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * @see Object#hashCode()
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">hashCode</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> h <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">hashCode</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+ h <span style="color:#666">=</span> h <span style="color:#666">*</span> 37 <span style="color:#666">+</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">int</span> <span style="color:#666">)</span> changeNumber<span style="color:#666">;</span>
+ h <span style="color:#666">=</span> h <span style="color:#666">*</span> 37 <span style="color:#666">+</span> <span style="color:#666">(</span> changeType <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">?</span> 0 <span style="color:#666">:</span> changeType<span style="color:#666">.</span><span style="color:#b44">hashCode</span><span style="color:#666">(</span><span style="color: [...]
+ h <span style="color:#666">=</span> h <span style="color:#666">*</span> 37 <span style="color:#666">+</span> <span style="color:#666">(</span> previousDn <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">?</span> 0 <span style="color:#666">:</span> previousDn<span style="color:#666">.</span><span style="color:#b44">hashCode</span><span style="color:#666">(</span><span style="color: [...]
+
+ <span style="color:#a2f;font-weight:bold">return</span> h<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">boolean</span> <span style="color:#00a000">equals</span><span style="color:#666">(</span> Object o <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> <span style="color:#666">!</span><span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">.</span><span style="color:#b44">equals</span><span style="color:#666">(</span> o <span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">false</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ EntryChange otherControl <span style="color:#666">=</span> <span style="color:#666">(</span> EntryChange <span style="color:#666">)</span> o<span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#666">(</span> changeNumber <span style="color:#666">=</span><span style="color:#666">=</span> otherControl<span style="color:#666">.</span><span style="color:#b44">getChangeNumber</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span> <span style="color:#666">&</span><span style="color:#666">&</span> <span style="color:#666">(</span> changeTy [...]
+ <span style="color:#666">&</span><span style="color:#666">&</span> <span style="color:#666">(</span> previousDn<span style="color:#666">.</span><span style="color:#b44">equals</span><span style="color:#666">(</span> otherControl<span style="color:#666">.</span><span style="color:#b44">getPreviousDn</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Return a String representing this EntryChangeControl.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> String <span style="color:#00a000">toString</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ StringBuilder sb <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> StringBuilder<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" Entry Change Control\n"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" oid : "</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> getOid<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span>< [...]
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" critical : "</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> isCritical<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">appen [...]
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" changeType : '"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> changeType <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="co [...]
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" previousDN : '"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> previousDn <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="co [...]
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> changeNumber <span style="color:#666">=</span><span style="color:#666">=</span> UNDEFINED_CHANGE_NUMBER <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" changeNumber : '"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">"UNDEFINED"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><spa [...]
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">else</span>
+ <span style="color:#666">{</span>
+ sb<span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span style="color:#b44">" changeNumber : '"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> changeNumber <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">append</span><span style="color:#666">(</span> <span sty [...]
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> sb<span style="color:#666">.</span><span style="color:#b44">toString</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>This is pretty much trivial.</p>
+<p>We now need a <em>Decorator</em> to manipulate this instance. Here is the code :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">EntryChangeDecorator</span> <span style="color:#a2f;font-weight:bold">extends</span> ControlDecorator<span style="color:#666"><</span>EntryChange<span style="color:#666">></span> <span style="color:# [...]
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">/** Default value when no change number is provided */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">static</span> <span style="color:#a2f;font-weight:bold">final</span> <span style="color:#0b0;font-weight:bold">int</span> UNDEFINED_CHANGE_NUMBER <span style="color:#666">=</span> <span style="color:#666">-</span>1<span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">/** A temporary storage for the previous Dn */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> previousDnBytes <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span><span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">/** The entry change global length */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#0b0;font-weight:bold">int</span> eccSeqLength<span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">/** An instance of this decoder */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#a2f;font-weight:bold">static</span> <span style="color:#a2f;font-weight:bold">final</span> Asn1Decoder DECODER <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> Asn1Decoder<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of EntryChangeDecoder wrapping a newly created
+</span><span style="color:#080;font-style:italic"> * EntryChange Control object.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param codec The LDAP service instance
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">EntryChangeDecorator</span><span style="color:#666">(</span> LdapApiService codec <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> codec<span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">new</span> EntryChangeImpl<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Creates a new instance of EntryChangeDecorator wrapping the supplied
+</span><span style="color:#080;font-style:italic"> * EntryChange Control.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param codec The LDAP service instance
+</span><span style="color:#080;font-style:italic"> * @param control The EntryChange Control to be decorated.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#00a000">EntryChangeDecorator</span><span style="color:#666">(</span> LdapApiService codec<span style="color:#666">,</span> EntryChange control <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">super</span><span style="color:#666">(</span> codec<span style="color:#666">,</span> control <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Internally used to not have to cast the decorated Control.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @return the decorated Control.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f;font-weight:bold">private</span> EntryChange <span style="color:#00a000">getEntryChange</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> getDecorated<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Compute the EntryChangeControl length
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * <pre>
+</span><span style="color:#080;font-style:italic"> * 0x30 L1
+</span><span style="color:#080;font-style:italic"> * |
+</span><span style="color:#080;font-style:italic"> * +--&gt; 0x0A 0x0(1-4) [1|2|4|8] (changeType)
+</span><span style="color:#080;font-style:italic"> * [+--&gt; 0x04 L2 previousDN]
+</span><span style="color:#080;font-style:italic"> * [+--&gt; 0x02 0x0(1-4) [0..2^63-1] (changeNumber)]
+</span><span style="color:#080;font-style:italic"> * </pre>
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @return the control length.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">computeLength</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#0b0;font-weight:bold">int</span> changeTypesLength <span style="color:#666">=</span> 1 <span style="color:#666">+</span> 1 <span style="color:#666">+</span> 1<span style="color:#666">;</span>
+
+ <span style="color:#0b0;font-weight:bold">int</span> previousDnLength <span style="color:#666">=</span> 0<span style="color:#666">;</span>
+ <span style="color:#0b0;font-weight:bold">int</span> changeNumberLength <span style="color:#666">=</span> 0<span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getPreviousDn<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ previousDnBytes <span style="color:#666">=</span> Strings<span style="color:#666">.</span><span style="color:#b44">getBytesUtf8</span><span style="color:#666">(</span> getPreviousDn<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getName</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ previousDnLength <span style="color:#666">=</span> 1 <span style="color:#666">+</span> TLV<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> previousDnBytes<span style="color:#666">.</span><span style="color:#b44">length</span> <span style="color:#666">)</span> <span style="color:#666">+</span> previousDnBytes<span style="color:#666">.</span><span style="color:#b44">length</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getChangeNumber<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> UNDEFINED_CHANGE_NUMBER <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ changeNumberLength <span style="color:#666">=</span> 1 <span style="color:#666">+</span> 1 <span style="color:#666">+</span> BerValue<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> getChangeNumber<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ eccSeqLength <span style="color:#666">=</span> changeTypesLength <span style="color:#666">+</span> previousDnLength <span style="color:#666">+</span> changeNumberLength<span style="color:#666">;</span>
+ valueLength <span style="color:#666">=</span> 1 <span style="color:#666">+</span> TLV<span style="color:#666">.</span><span style="color:#b44">getNbBytes</span><span style="color:#666">(</span> eccSeqLength <span style="color:#666">)</span> <span style="color:#666">+</span> eccSeqLength<span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> valueLength<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * Encodes the entry change control.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * @param buffer The encoded sink
+</span><span style="color:#080;font-style:italic"> * @return A ByteBuffer that contains the encoded PDU
+</span><span style="color:#080;font-style:italic"> * @throws EncoderException If anything goes wrong.
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> ByteBuffer <span style="color:#00a000">encode</span><span style="color:#666">(</span> ByteBuffer buffer <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> EncoderException
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> buffer <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">throw</span> <span style="color:#a2f;font-weight:bold">new</span> EncoderException<span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">err</span><span style="color:#666">(</span> I18n<span style="color:#666">.</span><span style="color:#b44">ERR_04023</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> UniversalTag<span style="color:#666">.</span><span style="color:#b44">SEQUENCE</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> TLV<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> eccSeqLength <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> UniversalTag<span style="color:#666">.</span><span style="color:#b44">ENUMERATED</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span> <span style="color:#666">)</span> 1 <span style="color:#666">)</span><span style="color:#666">;</span>
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> BerValue<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> getChangeType<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span> <spa [...]
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getPreviousDn<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ BerValue<span style="color:#666">.</span><span style="color:#b44">encode</span><span style="color:#666">(</span> buffer<span style="color:#666">,</span> previousDnBytes <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getChangeNumber<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> UNDEFINED_CHANGE_NUMBER <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ BerValue<span style="color:#666">.</span><span style="color:#b44">encode</span><span style="color:#666">(</span> buffer<span style="color:#666">,</span> getChangeNumber<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> buffer<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#00a000">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> value <span style="color:#666">=</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ computeLength<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ ByteBuffer buffer <span style="color:#666">=</span> ByteBuffer<span style="color:#666">.</span><span style="color:#b44">allocate</span><span style="color:#666">(</span> valueLength <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> UniversalTag<span style="color:#666">.</span><span style="color:#b44">SEQUENCE</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> TLV<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> eccSeqLength <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> UniversalTag<span style="color:#666">.</span><span style="color:#b44">ENUMERATED</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> <span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span> <span style="color:#666">)</span> 1 <span style="color:#666">)</span><span style="color:#666">;</span>
+ buffer<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span> BerValue<span style="color:#666">.</span><span style="color:#b44">getBytes</span><span style="color:#666">(</span> getChangeType<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getValue</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</sp [...]
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getPreviousDn<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">null</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ BerValue<span style="color:#666">.</span><span style="color:#b44">encode</span><span style="color:#666">(</span> buffer<span style="color:#666">,</span> previousDnBytes <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> getChangeNumber<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">!</span><span style="color:#666">=</span> UNDEFINED_CHANGE_NUMBER <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ BerValue<span style="color:#666">.</span><span style="color:#b44">encode</span><span style="color:#666">(</span> buffer<span style="color:#666">,</span> getChangeNumber<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ value <span style="color:#666">=</span> buffer<span style="color:#666">.</span><span style="color:#b44">array</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> Exception e <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">null</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+
+ <span style="color:#a2f;font-weight:bold">return</span> value<span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> ChangeType <span style="color:#00a000">getChangeType</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> getEntryChange<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getChangeType</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setChangeType</span><span style="color:#666">(</span> ChangeType changeType <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ getEntryChange<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setChangeType</span><span style="color:#666">(</span> changeType <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> Dn <span style="color:#00a000">getPreviousDn</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> getEntryChange<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getPreviousDn</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setPreviousDn</span><span style="color:#666">(</span> Dn previousDn <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ getEntryChange<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setPreviousDn</span><span style="color:#666">(</span> previousDn <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">long</span> <span style="color:#00a000">getChangeNumber</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> getEntryChange<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getChangeNumber</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">setChangeNumber</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">long</span> changeNumber <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ getEntryChange<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">setChangeNumber</span><span style="color:#666">(</span> changeNumber <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+
+ <span style="color:#080;font-style:italic">/**
+</span><span style="color:#080;font-style:italic"> * {@inheritDoc}
+</span><span style="color:#080;font-style:italic"> */</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> Asn1Object <span style="color:#00a000">decode</span><span style="color:#666">(</span> <span style="color:#0b0;font-weight:bold">byte</span><span style="color:#666">[</span><span style="color:#666">]</span> controlBytes <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> DecoderException
+ <span style="color:#666">{</span>
+ ByteBuffer bb <span style="color:#666">=</span> ByteBuffer<span style="color:#666">.</span><span style="color:#b44">wrap</span><span style="color:#666">(</span> controlBytes <span style="color:#666">)</span><span style="color:#666">;</span>
+ EntryChangeContainer container <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> EntryChangeContainer<span style="color:#666">(</span> getCodecService<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">,</span> <span style="color:#a2f;font-weight:bold">this</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ DECODER<span style="color:#666">.</span><span style="color:#b44">decode</span><span style="color:#666">(</span> bb<span style="color:#666">,</span> container <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">this</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div>
<div class="nav">
diff --git a/content/api/user-guide/2.10-ldap-connection-template.html b/content/api/user-guide/2.10-ldap-connection-template.html
index e7225fe..2930dd6 100644
--- a/content/api/user-guide/2.10-ldap-connection-template.html
+++ b/content/api/user-guide/2.10-ldap-connection-template.html
@@ -169,202 +169,176 @@
<p>Conceptually it uses the Template Method design pattern to do all of the boiler plate work for you. It can give control back as needed for special cases.</p>
<h2 id="managing-connections">Managing Connections</h2>
<p>The connection template manages connections through a connection pool. The connection pool must be supplied to the constructor:</p>
-<pre><code>:::Java
-LdapConnectionConfig config = new LdapConnectionConfig();
-config.setLdapHost( hostname );
-config.setLdapPort( port );
-config.setName( adminDn );
-config.setCredentials( adminPassword );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> LdapConnectionConfig config <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> LdapConnectionConfig<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ config<span style="color:#666">.</span><span style="color:#b44">setLdapHost</span><span style="color:#666">(</span> hostname <span style="color:#666">)</span><span style="color:#666">;</span>
+ config<span style="color:#666">.</span><span style="color:#b44">setLdapPort</span><span style="color:#666">(</span> port <span style="color:#666">)</span><span style="color:#666">;</span>
+ config<span style="color:#666">.</span><span style="color:#b44">setName</span><span style="color:#666">(</span> adminDn <span style="color:#666">)</span><span style="color:#666">;</span>
+ config<span style="color:#666">.</span><span style="color:#b44">setCredentials</span><span style="color:#666">(</span> adminPassword <span style="color:#666">)</span><span style="color:#666">;</span>
-DefaultLdapConnectionFactory factory = new DefaultLdapConnectionFactory( config );
-factory.setTimeOut( connectionTimeout );
+ DefaultLdapConnectionFactory factory <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultLdapConnectionFactory<span style="color:#666">(</span> config <span style="color:#666">)</span><span style="color:#666">;</span>
+ factory<span style="color:#666">.</span><span style="color:#b44">setTimeOut</span><span style="color:#666">(</span> connectionTimeout <span style="color:#666">)</span><span style="color:#666">;</span>
-// optional, values below are defaults
-GenericObjectPool.Config poolConfig = new GenericObjectPool.Config();
-poolConfig.lifo = true;
-poolConfig.maxActive = 8;
-poolConfig.maxIdle = 8;
-poolConfig.maxWait = -1L;
-poolConfig.minEvictableIdleTimeMillis = 1000L * 60L * 30L;
-poolConfig.minIdle = 0;
-poolConfig.numTestsPerEvictionRun = 3;
-poolConfig.softMinEvictableIdleTimeMillis = -1L;
-poolConfig.testOnBorrow = false;
-poolConfig.testOnReturn = false;
-poolConfig.testWhileIdle = false;
-poolConfig.timeBetweenEvictionRunsMillis = -1L;
-poolConfig.whenExhaustedAction = GenericObjectPool.WHEN_EXHAUSTED_BLOCK;
+ <span style="color:#080;font-style:italic">// optional, values below are defaults
+</span><span style="color:#080;font-style:italic"></span> GenericObjectPool<span style="color:#666">.</span><span style="color:#b44">Config</span> poolConfig <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> GenericObjectPool<span style="color:#666">.</span><span style="color:#b44">Config</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">lifo</span> <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">true</span><span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">maxActive</span> <span style="color:#666">=</span> 8<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">maxIdle</span> <span style="color:#666">=</span> 8<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">maxWait</span> <span style="color:#666">=</span> <span style="color:#666">-</span>1L<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">minEvictableIdleTimeMillis</span> <span style="color:#666">=</span> 1000L <span style="color:#666">*</span> 60L <span style="color:#666">*</span> 30L<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">minIdle</span> <span style="color:#666">=</span> 0<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">numTestsPerEvictionRun</span> <span style="color:#666">=</span> 3<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">softMinEvictableIdleTimeMillis</span> <span style="color:#666">=</span> <span style="color:#666">-</span>1L<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">testOnBorrow</span> <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">false</span><span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">testOnReturn</span> <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">false</span><span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">testWhileIdle</span> <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">false</span><span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">timeBetweenEvictionRunsMillis</span> <span style="color:#666">=</span> <span style="color:#666">-</span>1L<span style="color:#666">;</span>
+ poolConfig<span style="color:#666">.</span><span style="color:#b44">whenExhaustedAction</span> <span style="color:#666">=</span> GenericObjectPool<span style="color:#666">.</span><span style="color:#b44">WHEN_EXHAUSTED_BLOCK</span><span style="color:#666">;</span>
-// could use DefaultPoolableLdapConnectionFactory instead
-// see javadoc for ValidatingPoolableLdapConnectionFactory
-// for an explanation
-LdapConnectionTemplate ldapConnectionTemplate =
- new LdapConnectionTemplate( new LdapConnectionPool(
- new ValidatingPoolableLdapConnectionFactory( factory ), poolConfig ) );
-</code></pre>
-<p>This may look complicated, but most of the parameters are optional and it’s an easy way for you to manage connections in a safe and efficient manner.</p>
+ <span style="color:#080;font-style:italic">// could use DefaultPoolableLdapConnectionFactory instead
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#080;font-style:italic">// see javadoc for ValidatingPoolableLdapConnectionFactory
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#080;font-style:italic">// for an explanation
+</span><span style="color:#080;font-style:italic"></span> LdapConnectionTemplate ldapConnectionTemplate <span style="color:#666">=</span>
+ <span style="color:#a2f;font-weight:bold">new</span> LdapConnectionTemplate<span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">new</span> LdapConnectionPool<span style="color:#666">(</span>
+ <span style="color:#a2f;font-weight:bold">new</span> ValidatingPoolableLdapConnectionFactory<span style="color:#666">(</span> factory <span style="color:#666">)</span><span style="color:#666">,</span> poolConfig <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>This may look complicated, but most of the parameters are optional and it’s an easy way for you to manage connections in a safe and efficient manner.</p>
<h2 id="providing-factory-methods-for-model-objects">Providing Factory Methods For Model Objects</h2>
<p>The connection template implements an interface called the ModelFactory. Any implementation of this factory can be injected into the template once it is constructed. By default, it uses ModelFactoryImpl which in turn constructs the standard Apache LDAP API model objects. This abstraction frees you from having to be concerned with implementation details while still giving you the power to override the default behavior as you see fit.</p>
-<pre><code>:::Java
-ModelFactory modelFactory = new MyCustomModelFactory();
-ldapConnectionTemplate.setModelFactory( modelFactory );
-</code></pre>
-<h2 id="providing-crud-methods">Providing CRUD Methods</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> ModelFactory modelFactory <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> MyCustomModelFactory<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">setModelFactory</span><span style="color:#666">(</span> modelFactory <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><h2 id="providing-crud-methods">Providing CRUD Methods</h2>
<p>The standard CRUD methods are provided (<em>though in this case Add, Lookup, Modify, Delete</em>) with a couple useful overloads. Add, Delete, and Modify all provide at least 2 approaches. The first is creating your own XxxRequest objects and supplying that to the method. These request objects can be created using the ModelFactory methods provided by LdapConnectionTemplate. The second, more elegant solution, is to use the DN and RequestBuilder approach. This approach will generat [...]
<p>Add provides the standard approaches of supplying your own AddRequest and using RequestBuilder, as well as a third shortcut approach where you supply all the attributes instead of a RequestBuilder:</p>
-<pre><code>:::Java
-// using RequestBuilder
-AddResponse response = ldapConnectionTemplate.add(
- ldapConnectionTemplate.newDn( "uid=kermitthefrog,ou=muppets,dc=muppets,dc=org" ),
- new RequestBuilder<AddRequest>() {
- @Override
- public void buildRequest( AddRequest request ) throws LdapException {
- request.getEntry()
- .add( "objectClass", "top", "person", "organizationalPerson", "inetOrgPerson" )
- .add( "cn", "Kermit The Frog" )
- .add( "givenName", "Kermit" )
- .add( "sn", "The Frog" )
- .add( "mail", "kermitthefrog@muppets.org" )
- .add( "uid", "kermitthefrog" );
- }
- } );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// using RequestBuilder
+</span><span style="color:#080;font-style:italic"></span> AddResponse response <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=kermitthefrog,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ <span style="color:#a2f;font-weight:bold">new</span> RequestBuilder<span style="color:#666"><</span>AddRequest<span style="color:#666">></span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">{</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">buildRequest</span><span style="color:#666">(</span> AddRequest request <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> LdapException <span style="color:#666">{</span>
+ request<span style="color:#666">.</span><span style="color:#b44">getEntry</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> <span style="color:#b44">"objectClass"</span><span style="color:#666">,</span> <span style="color:#b44">"top"</span><span style="color:#666">,</span> <span style="color:#b44">"person"</span><span style="color:#666">,</span> <span style="color:#b44">"organizationalPerson"</span><span style="color:#666">,</span> <span style="color:#b44">& [...]
+ <span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> <span style="color:#b44">"cn"</span><span style="color:#666">,</span> <span style="color:#b44">"Kermit The Frog"</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span> <span style="color:#b44">"Kermit"</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> <span style="color:#b44">"sn"</span><span style="color:#666">,</span> <span style="color:#b44">"The Frog"</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> <span style="color:#b44">"mail"</span><span style="color:#666">,</span> <span style="color:#b44">"kermitthefrog@muppets.org"</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> <span style="color:#b44">"uid"</span><span style="color:#666">,</span> <span style="color:#b44">"kermitthefrog"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">// using Attributes list
+</span><span style="color:#080;font-style:italic"></span> AddResponse response <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=misspiggy,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newAttribute</span><span style="color:#666">(</span> <span style="color:#b44">"objectClass"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"top"</span><span style="color:#666">,</span> <span style="color:#b44">"person"</span><span style="color:#666">,</span> <span style="color:#b44">"organizationalPerson"</span><span style="color:#666">,</span> <span style="color:#b44">"inetOrgPerson"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newAttribute</span><span style="color:#666">(</span> <span style="color:#b44">"cn"</span><span style="color:#666">,</span> <span style="color:#b44">"Miss Piggy"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newAttribute</span><span style="color:#666">(</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span> <span style="color:#b44">"Miss"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newAttribute</span><span style="color:#666">(</span> <span style="color:#b44">"sn"</span><span style="color:#666">,</span> <span style="color:#b44">"Piggy"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newAttribute</span><span style="color:#666">(</span> <span style="color:#b44">"mail"</span><span style="color:#666">,</span> <span style="color:#b44">"misspiggy@muppets.org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newAttribute</span><span style="color:#666">(</span> <span style="color:#b44">"uid"</span><span style="color:#666">,</span> <span style="color:#b44">"misspiggy"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>Modify simply supplies the 2 standard approaches:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// using RequestBuilder
+</span><span style="color:#080;font-style:italic"></span> ModifyResponse response <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=misspiggy,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ <span style="color:#a2f;font-weight:bold">new</span> RequestBuilder<span style="color:#666"><</span>ModifyRequest<span style="color:#666">></span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">{</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">buildRequest</span><span style="color:#666">(</span> ModifyRequest request <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> LdapException <span style="color:#666">{</span>
+ request<span style="color:#666">.</span><span style="color:#b44">replace</span><span style="color:#666">(</span> <span style="color:#b44">"sn"</span><span style="color:#666">,</span> <span style="color:#b44">"The Frog"</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">replace</span><span style="color:#666">(</span> <span style="color:#b44">"cn"</span><span style="color:#666">,</span> <span style="color:#b44">"Miss The Frog"</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">replace</span><span style="color:#666">(</span> <span style="color:#b44">"mail"</span><span style="color:#666">,</span> <span style="color:#b44">"missthefrog@muppets.org"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>Delete provides the 2 standard approaches plus an additional DN-only option as that is most likely enough:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// using DN only
+</span><span style="color:#080;font-style:italic"></span> DeleteResponse response <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">delete</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=misspiggy,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>Lookup is a different story in that it is an accessor (instead of mutator) so its interface must provide a way of handling the expected response data. To that end, we supply an EntryMapper. EntryMapper defines how a returned ldap entry should be interpreted. This is typically used to construct a domain object:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// using a previously defined EntryMapper
+</span><span style="color:#080;font-style:italic"></span> Muppet kermit <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">lookup</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=kermitthefrog,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ muppetEntryMapper <span style="color:#666">)</span><span style="color:#666">;</span>
-// using Attributes list
-AddResponse response = ldapConnectionTemplate.add(
- ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ),
- ldapConnectionTemplate.newAttribute( "objectClass",
- "top", "person", "organizationalPerson", "inetOrgPerson" ),
- ldapConnectionTemplate.newAttribute( "cn", "Miss Piggy" ),
- ldapConnectionTemplate.newAttribute( "givenName", "Miss" ),
- ldapConnectionTemplate.newAttribute( "sn", "Piggy" ),
- ldapConnectionTemplate.newAttribute( "mail", "misspiggy@muppets.org" ),
- ldapConnectionTemplate.newAttribute( "uid", "misspiggy" ) );
-</code></pre>
-<p>Modify simply supplies the 2 standard approaches:</p>
-<pre><code>:::Java
-// using RequestBuilder
-ModifyResponse response = ldapConnectionTemplate.modify(
- ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ),
- new RequestBuilder<ModifyRequest>() {
- @Override
- public void buildRequest( ModifyRequest request ) throws LdapException {
- request.replace( "sn", "The Frog" )
- .replace( "cn", "Miss The Frog" )
- .replace( "mail", "missthefrog@muppets.org" );
- }
- } );
-</code></pre>
-<p>Delete provides the 2 standard approaches plus an additional DN-only option as that is most likely enough:</p>
-<pre><code>:::Java
-// using DN only
-DeleteResponse response = ldapConnectionTemplate.delete(
- ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ) );
-</code></pre>
-<p>Lookup is a different story in that it is an accessor (instead of mutator) so its interface must provide a way of handling the expected response data. To that end, we supply an EntryMapper. EntryMapper defines how a returned ldap entry should be interpreted. This is typically used to construct a domain object:</p>
-<pre><code>:::Java
-// using a previously defined EntryMapper
-Muppet kermit = ldapConnectionTemplate.lookup(
- ldapConnectionTemplate.newDn( "uid=kermitthefrog,ou=muppets,dc=muppets,dc=org" ),
- muppetEntryMapper );
-
-// using an inline defined EntityMapper
-String email = ldapConnectionTemplate.lookup(
- ldapConnectionTemplate.newDn( "uid=kermitthefrog,ou=muppets,dc=muppets,dc=org" ),
- new String[] { "mail" }, // attribute list
- new EntryMapper<String>() {
- @Override
- public String map( Entry entry ) throws LdapException {
- return entry.get( "mail" ).getString();
- }
- } );
-</code></pre>
-<p>More information on EntryMapper can be found in the <a href="#handling-search-result-iteration">Handling Search Result Iteration</a> section.</p>
+ <span style="color:#080;font-style:italic">// using an inline defined EntityMapper
+</span><span style="color:#080;font-style:italic"></span> String email <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">lookup</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=kermitthefrog,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ <span style="color:#a2f;font-weight:bold">new</span> String<span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#666">{</span> <span style="color:#b44">"mail"</span> <span style="color:#666">}</span><span style="color:#666">,</span> <span style="color:#080;font-style:italic">// attribute list
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#a2f;font-weight:bold">new</span> EntryMapper<span style="color:#666"><</span>String<span style="color:#666">></span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">{</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> String <span style="color:#00a000">map</span><span style="color:#666">(</span> Entry entry <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> LdapException <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> entry<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span> <span style="color:#b44">"mail"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getString</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>More information on EntryMapper can be found in the <a href="#handling-search-result-iteration">Handling Search Result Iteration</a> section.</p>
<h2 id="handling-search-result-iteration">Handling Search Result Iteration</h2>
<p>Searching usually contains a lot of boilerplate code for building requests and iterating through its responses. This template does the work for you. It iterates over the entire result set, feeds each entry through an EntryMapper, and assembles the results into a list tht is returned to the caller. All you have to do is provide the EntryMapper for mapping a single entry to a domain object. EntryMapper itself is a very simple interface with one method. As you saw before in the looku [...]
-<pre><code>:::Java
-// typically mappers are reused, so define a static member
-private static final EntryMapper<Muppet> muppetEntryMapper =
- new EntryMapper<Muppet>() {
- @Override
- public Muppet map( Entry entry ) throws LdapException {
- return new Muppet.Builder()
- .setId( entry.getDn() )
- .setFirstName( entry.get( "givenName" ).getString() )
- .setLastName( entry.get( "sn" ).getString() )
- .setEmailAddress( entry.get( "mail" ).getString() )
- .build();
- }
- };
-</code></pre>
-<p>And now your searches become much simpler:</p>
-<pre><code>:::Java
-List<Muppet> allTheMuppets = ldapConnectionTemplate.search(
- "ou=muppets,dc=muppets,dc=org",
- "(objectClass=inetOrgPerson)",
- SearchScope.ONELEVEL,
- muppetEntryMapper );
-</code></pre>
-<p>Now that is just plain <em><strong>SIMPLE</strong></em>. The search method has many overloads to simplify usages for the most common LDAP operations. There is also a searchFirst method which provides all the same overloads and is designed to return the first matching result:</p>
-<pre><code>:::Java
-Muppet kermit = ldapConnectionTemplate.searchFirst(
- "ou=muppets,dc=muppets,dc=org",
- "(mail=kermitthefrog@muppets.org)",
- SearchScope.ONELEVEL,
- muppetEntryMapper );
-</code></pre>
-<p>It is also natural to pair the search function with the FilterBuilder:</p>
-<pre><code>:::Java
-import static org.apache.directory.ldap.client.api.search.FilterBuilder.equal;
-import static org.apache.directory.ldap.client.api.search.FilterBuilder.or;
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// typically mappers are reused, so define a static member
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#a2f;font-weight:bold">private</span> <span style="color:#a2f;font-weight:bold">static</span> <span style="color:#a2f;font-weight:bold">final</span> EntryMapper<span style="color:#666"><</span>Muppet<span style="color:#666">></span> muppetEntryMapper <span style="color:#666">=</span>
+ <span style="color:#a2f;font-weight:bold">new</span> EntryMapper<span style="color:#666"><</span>Muppet<span style="color:#666">></span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">{</span>
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> Muppet <span style="color:#00a000">map</span><span style="color:#666">(</span> Entry entry <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> LdapException <span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">new</span> Muppet<span style="color:#666">.</span><span style="color:#b44">Builder</span><span style="color:#666">(</span><span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">setId</span><span style="color:#666">(</span> entry<span style="color:#666">.</span><span style="color:#b44">getDn</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">setFirstName</span><span style="color:#666">(</span> entry<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span> <span style="color:#b44">"givenName"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getString</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">setLastName</span><span style="color:#666">(</span> entry<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span> <span style="color:#b44">"sn"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getString</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">setEmailAddress</span><span style="color:#666">(</span> entry<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span> <span style="color:#b44">"mail"</span> <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getString</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">.</span><span style="color:#b44">build</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span><span style="color:#666">;</span>
+</code></pre></div><p>And now your searches become much simpler:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> List<span style="color:#666"><</span>Muppet<span style="color:#666">></span> allTheMuppets <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">search</span><span style="color:#666">(</span>
+ <span style="color:#b44">"ou=muppets,dc=muppets,dc=org"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"(objectClass=inetOrgPerson)"</span><span style="color:#666">,</span>
+ SearchScope<span style="color:#666">.</span><span style="color:#b44">ONELEVEL</span><span style="color:#666">,</span>
+ muppetEntryMapper <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>Now that is just plain <em><strong>SIMPLE</strong></em>. The search method has many overloads to simplify usages for the most common LDAP operations. There is also a searchFirst method which provides all the same overloads and is designed to return the first matching result:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> Muppet kermit <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">searchFirst</span><span style="color:#666">(</span>
+ <span style="color:#b44">"ou=muppets,dc=muppets,dc=org"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"(mail=kermitthefrog@muppets.org)"</span><span style="color:#666">,</span>
+ SearchScope<span style="color:#666">.</span><span style="color:#b44">ONELEVEL</span><span style="color:#666">,</span>
+ muppetEntryMapper <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>It is also natural to pair the search function with the FilterBuilder:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">import static</span> <span style="color:#00f;font-weight:bold">org.apache.directory.ldap.client.api.search.FilterBuilder.equal</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">import static</span> <span style="color:#00f;font-weight:bold">org.apache.directory.ldap.client.api.search.FilterBuilder.or</span><span style="color:#666">;</span>
-...
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
- Muppet kermit = ldapConnectionTemplate.search(
- "ou=muppets,dc=muppets,dc=org",
- or(
- equal( "mail", "kermitthefrog@muppets.org" ),
- equal( "mail", "misspiggy@muppets.org" ) ),
- SearchScope.ONELEVEL,
- muppetEntryMapper );
-</code></pre>
-<p>This has the added benefit of ensuring that your search filter has been property encoded per <a href="https://tools.ietf.org/html/rfc4515.html#section-3">RFC4515 section 3</a>. For more information, see <a href="/api/user-guide/2.11-filter-builder.html">Filter Builder</a>.</p>
+ Muppet kermit <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">search</span><span style="color:#666">(</span>
+ <span style="color:#b44">"ou=muppets,dc=muppets,dc=org"</span><span style="color:#666">,</span>
+ or<span style="color:#666">(</span>
+ equal<span style="color:#666">(</span> <span style="color:#b44">"mail"</span><span style="color:#666">,</span> <span style="color:#b44">"kermitthefrog@muppets.org"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ equal<span style="color:#666">(</span> <span style="color:#b44">"mail"</span><span style="color:#666">,</span> <span style="color:#b44">"misspiggy@muppets.org"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ SearchScope<span style="color:#666">.</span><span style="color:#b44">ONELEVEL</span><span style="color:#666">,</span>
+ muppetEntryMapper <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>This has the added benefit of ensuring that your search filter has been property encoded per <a href="https://tools.ietf.org/html/rfc4515.html#section-3">RFC4515 section 3</a>. For more information, see <a href="/api/user-guide/2.11-filter-builder.html">Filter Builder</a>.</p>
<h2 id="providing-simplified-password-policy-aware-authenticationpassword-modification-methods">Providing Simplified, Password Policy Aware, Authentication/Password Modification Methods</h2>
<p>One of the most common usages of LDAP is as an identity provider. As such, the most common operation is authentication, and password management. If your LDAP server supports the <a href="http://tools.ietf.org/html/draft-behera-ldap-password-policy-10">password policy control</a> then the authenticate method is very handy:</p>
-<pre><code>:::Java
-// throws PasswordException if authentication fails
-PasswordWarning warning = ldapConnectionTemplate.authenticate(
- ldapConnectionTemplate.newDn( "uid=" + uid + ", ou=people, dc=example, dc=com" ),
- password );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// throws PasswordException if authentication fails
+</span><span style="color:#080;font-style:italic"></span> PasswordWarning warning <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">authenticate</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid="</span> <span style="color:#666">+</span> uid <span style="color:#666">+</span> <span style="color:#b44">", ou=people, dc=example, dc=com"</span> <span style="color:#666">)</span><span style="color:#666">,</span>
+ password <span style="color:#666">)</span><span style="color:#666">;</span>
-// or if you authenticate using an attribute not in the dn
-PasswordWarning warning = ldapConnectionTemplate.authenticate(
- "ou=people,dc=example,dc=com",
- "(mail=kermitthefrog@muppets.com)",
- SearchScope.ONELEVEL,
- "set4now".toCharArray() );
-</code></pre>
-<p>In this case, if authentication failed, a PasswordException is thrown. If authentication was successful, any warnings will be returned in the PasswordWarning object, or null will be returned if there are no warnings.</p>
+ <span style="color:#080;font-style:italic">// or if you authenticate using an attribute not in the dn
+</span><span style="color:#080;font-style:italic"></span> PasswordWarning warning <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">authenticate</span><span style="color:#666">(</span>
+ <span style="color:#b44">"ou=people,dc=example,dc=com"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"(mail=kermitthefrog@muppets.com)"</span><span style="color:#666">,</span>
+ SearchScope<span style="color:#666">.</span><span style="color:#b44">ONELEVEL</span><span style="color:#666">,</span>
+ <span style="color:#b44">"set4now"</span><span style="color:#666">.</span><span style="color:#b44">toCharArray</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>In this case, if authentication failed, a PasswordException is thrown. If authentication was successful, any warnings will be returned in the PasswordWarning object, or null will be returned if there are no warnings.</p>
<p>Modifying a password is simple as well:</p>
-<pre><code>:::Java
-// using administrator account to modify a users password
-ldapConnectionTemplate.modifyPassword( userDn, password );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// using administrator account to modify a users password
+</span><span style="color:#080;font-style:italic"></span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">modifyPassword</span><span style="color:#666">(</span> userDn<span style="color:#666">,</span> password <span style="color:#666">)</span><span style="color:#666">;</span>
-// or user account modifying their own password
-ldapConnectionTemplate.modifyPassword( userDn, oldPassword, newPassword );
+ <span style="color:#080;font-style:italic">// or user account modifying their own password
+</span><span style="color:#080;font-style:italic"></span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">modifyPassword</span><span style="color:#666">(</span> userDn<span style="color:#666">,</span> oldPassword<span style="color:#666">,</span> newPassword <span style="color:#666">)</span><span style="color:#666">;</span>
-// or if you want want more control
-ldapConnectionTemplate.modifyPassword( userDn, oldPassword, newPassword, asAdmin );
-</code></pre>
-<p>If you modify the password as an administrator, then the oldPassword is not required, and if your password policy is set to, the password reset flag will be set causing a PasswordWarning to be returned the next time authenticate was called for that user.</p>
+ <span style="color:#080;font-style:italic">// or if you want want more control
+</span><span style="color:#080;font-style:italic"></span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">modifyPassword</span><span style="color:#666">(</span> userDn<span style="color:#666">,</span> oldPassword<span style="color:#666">,</span> newPassword<span style="color:#666">,</span> asAdmin <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>If you modify the password as an administrator, then the oldPassword is not required, and if your password policy is set to, the password reset flag will be set causing a PasswordWarning to be returned the next time authenticate was called for that user.</p>
<h2 id="other-useful-methods">Other Useful Methods</h2>
<p>The template provides a method that checks the response and throws an exception if the request was unsuccessful. It was designed to be chained:</p>
-<pre><code>:::Java
-// using DN only
-DeleteResponse response = ldapConnectionTemplate.responseOrException(
- ldapConnectionTemplate.delete(
- ldapConnectionTemplate.newDn( "uid=misspiggy,ou=muppets,dc=muppets,dc=org" ) ) );
-</code></pre>
-
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">// using DN only
+</span><span style="color:#080;font-style:italic"></span> DeleteResponse response <span style="color:#666">=</span> ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">responseOrException</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">delete</span><span style="color:#666">(</span>
+ ldapConnectionTemplate<span style="color:#666">.</span><span style="color:#b44">newDn</span><span style="color:#666">(</span> <span style="color:#b44">"uid=misspiggy,ou=muppets,dc=muppets,dc=org"</span> <span style="color:#666">)</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div>
<div class="nav">
diff --git a/content/api/user-guide/2.2-binding-unbinding.html b/content/api/user-guide/2.2-binding-unbinding.html
index d703588..a402ea2 100644
--- a/content/api/user-guide/2.2-binding-unbinding.html
+++ b/content/api/user-guide/2.2-binding-unbinding.html
@@ -180,35 +180,29 @@
<p>The first one is the easiest, but depending on the server’s configuration, will be accepted or rejected (not all servers allow anonymous binds)</p>
<p>Most of the time, the <em>bind</em> operation will not return anything. You either get bound, or will receive an <em>LdapException</em> if an error occurs.</p>
<p>Issuing an anonymous bind is simple, you neither provide a user nor a password:</p>
-<pre><code>:::Java
-@Test
-public void testAnonymousBindRequest() throws Exception
-{
- connection.bind();
-}
-</code></pre>
-<p>Issuing a user/password bind is slightly more complex, because those credentials must be included:</p>
-<pre><code>:::Java
-@Test
-public void testSimpleBindRequest() throws Exception
-{
- connection.bind( "uid=admin,ou=system", "secret" );
-}
-</code></pre>
-<blockquote>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testAnonymousBindRequest</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Issuing a user/password bind is slightly more complex, because those credentials must be included:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testSimpleBindRequest</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> <span style="color:#b44">"uid=admin,ou=system"</span><span style="color:#666">,</span> <span style="color:#b44">"secret"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><blockquote>
<p><strong>Note</strong> It’s important to note that the user’s name is a <em><a href="6.9-dn.html">Dn</a></em>, not a simple name like ‘John Doe”</p>
</blockquote>
<p>Last, not least, there is a quite unknown feature in <strong>LDAP</strong> bind that allows you to issue a Bind request without providing a password. It’s equivalent to an anonymous bind, except that the server can log the user’s name, thus being able to trace what the user does. Servers might forbid such bind, and this will be the case if the server disallow anonymous binds.</p>
<p>Note that this kind of bind will be supported only if the server allows anonymous binds. It’s not supported by <em>ApacheDS</em>.</p>
-<pre><code>:::Java
-@Test
-public void testSimpleBindRequest() throws Exception
-{
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testSimpleBindRequest</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
- connection.bind( "uid=admin,ou=system" );
-}
-</code></pre>
-<h3 id="sasl-binding">SASL Binding</h3>
+ connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> <span style="color:#b44">"uid=admin,ou=system"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h3 id="sasl-binding">SASL Binding</h3>
<p>There are various <strong>SASL</strong> mechanisms that can be used to bind to a <strong>LDAP</strong> server. The <strong>Apache LDAP API</strong> support the following 5 mechanisms:</p>
<h4 id="plain">PLAIN</h4>
<p>To be completed…</p>
@@ -220,67 +214,60 @@ public void testSimpleBindRequest() throws Exception
<p>To be completed…</p>
<h4 id="gssapi">GSSAPI</h4>
<p>First, non-trivial <strong>Kerberos</strong> authentication requires configuration. Creating a <strong>Kerberos</strong> configuration is not well documented elsewhere, so we include here sample code. One approach is to create a <strong>JAAS</strong> configuration file. Here’s what such a file might contain:</p>
-<pre><code>myapp {
- com.sun.security.auth.module.Krb5LoginModule required debug=true useKeyTab=true principal="host/ilab2.myorg.org@MYORG.ORG" refreshKrb5Config=true keyTab="/etc/krb5.keytab";
-};
-</code></pre>
-<p>See online documentation for <em>Krb5LoginModule</em> for possible options. This example uses the host’s principal, stored in <em>/etc/krb5.keytab</em>. What goes after <strong>@</strong> is the <strong>Kerberos</strong> domain name.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> myapp {
+ com.sun.security.auth.module.Krb5LoginModule required debug=true useKeyTab=true principal="host/ilab2.myorg.org@MYORG.ORG" refreshKrb5Config=true keyTab="/etc/krb5.keytab";
+ };
+</code></pre></div><p>See online documentation for <em>Krb5LoginModule</em> for possible options. This example uses the host’s principal, stored in <em>/etc/krb5.keytab</em>. What goes after <strong>@</strong> is the <strong>Kerberos</strong> domain name.</p>
<p>Note that if you specify a credential cache, the cache must be in a file. Many operating systems now put the user’s credentials in <strong>KEYRING</strong> or <strong>KCM</strong>. That worn’t work with Java.</p>
<p><em>“myapp”</em> is the name supplied as the login context name. See the code below.</p>
<p>When you run the program, you must tell java where the configuration file is. e.g. <em>“java -Djava.security.auth.login.config=jaas.config”</em>.</p>
<p>Here is code to connect to ldap with this configuration. We assume that <em>ldapNetworkConnection</em> has already been opened using connect.</p>
-<pre><code>:::Java
-saslGssApiRequest = new SaslGssApiRequest();
-saslGssApiRequest.setLoginModuleConfiguration(Configuration.getConfiguration());
-saslGssApiRequest.setLoginContextName( "myapp");
-saslGssApiRequest.setMutualAuthentication( true );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> saslGssApiRequest <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> SaslGssApiRequest<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ saslGssApiRequest<span style="color:#666">.</span><span style="color:#b44">setLoginModuleConfiguration</span><span style="color:#666">(</span>Configuration<span style="color:#666">.</span><span style="color:#b44">getConfiguration</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ saslGssApiRequest<span style="color:#666">.</span><span style="color:#b44">setLoginContextName</span><span style="color:#666">(</span> <span style="color:#b44">"myapp"</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ saslGssApiRequest<span style="color:#666">.</span><span style="color:#b44">setMutualAuthentication</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">true</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-try {
- BindResponse br = ldapNetworkConnection.bind( saslGssApiRequest );
- ldapNetworkConnection.startTls();
-} catch ( LdapException e ) {
- e.printStackTrace();
-}
-</code></pre>
-<p>At this point you can do operations such as search. Note that the argument to <em>setLoginContextName</em> must match the name in the configuration file. This sample uses mutual authentication. It is possible that some <strong>LDAP</strong> servers might not support that. If so you can set it to false. You may not need <em>startTls</em> if the connection is already secure.</p>
+ <span style="color:#a2f;font-weight:bold">try</span> <span style="color:#666">{</span>
+ BindResponse br <span style="color:#666">=</span> ldapNetworkConnection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> saslGssApiRequest <span style="color:#666">)</span><span style="color:#666">;</span>
+ ldapNetworkConnection<span style="color:#666">.</span><span style="color:#b44">startTls</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span> <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> LdapException e <span style="color:#666">)</span> <span style="color:#666">{</span>
+ e<span style="color:#666">.</span><span style="color:#b44">printStackTrace</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>At this point you can do operations such as search. Note that the argument to <em>setLoginContextName</em> must match the name in the configuration file. This sample uses mutual authentication. It is possible that some <strong>LDAP</strong> servers might not support that. If so you can set it to false. You may not need <em>startTls</em> if the connection is already secure.</p>
<p>Sometimes it is more convenient to supply the configuration information programmatically. Here is an example that sets the same options as the config file</p>
-<pre><code>:::Java
-class KerberosConfiguration extends Configuration {
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">KerberosConfiguration</span> <span style="color:#a2f;font-weight:bold">extends</span> Configuration <span style="color:#666">{</span>
- @Override
- public AppConfigurationEntry[] getAppConfigurationEntry(String name) {
- Map<String, String> options = new HashMap<String, String>();
- options.put("useKeyTab", "true");
- try {
- options.put("principal", "host/" + InetAddress.getLocalHost().getCanonicalHostName() + “@MYORG.ORG”);
- } catch (Exception e){
- System.out.println("Can't find our hostname " + e);
- }
- options.put("refreshKrb5Config", "true");
- options.put("keyTab", "/etc/krb5.keytab");
- options.put("debug", "true");
+ <span style="color:#a2f">@Override</span>
+ <span style="color:#a2f;font-weight:bold">public</span> AppConfigurationEntry<span style="color:#666">[</span><span style="color:#666">]</span> <span style="color:#00a000">getAppConfigurationEntry</span><span style="color:#666">(</span>String name<span style="color:#666">)</span> <span style="color:#666">{</span>
+ Map<span style="color:#666"><</span>String<span style="color:#666">,</span> String<span style="color:#666">></span> options <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> HashMap<span style="color:#666"><</span>String<span style="color:#666">,</span> String<span style="color:#666">></span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ options<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span><span style="color:#b44">"useKeyTab"</span><span style="color:#666">,</span> <span style="color:#b44">"true"</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#a2f;font-weight:bold">try</span> <span style="color:#666">{</span>
+ options<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span><span style="color:#b44">"principal"</span><span style="color:#666">,</span> <span style="color:#b44">"host/"</span> <span style="color:#666">+</span> InetAddress<span style="color:#666">.</span><span style="color:#b44">getLocalHost</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="c [...]
+ <span style="color:#666">}</span> <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span>Exception e<span style="color:#666">)</span><span style="color:#666">{</span>
+ System<span style="color:#666">.</span><span style="color:#b44">out</span><span style="color:#666">.</span><span style="color:#b44">println</span><span style="color:#666">(</span><span style="color:#b44">"Can't find our hostname "</span> <span style="color:#666">+</span> e<span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ options<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span><span style="color:#b44">"refreshKrb5Config"</span><span style="color:#666">,</span> <span style="color:#b44">"true"</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ options<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span><span style="color:#b44">"keyTab"</span><span style="color:#666">,</span> <span style="color:#b44">"/etc/krb5.keytab"</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ options<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span><span style="color:#b44">"debug"</span><span style="color:#666">,</span> <span style="color:#b44">"true"</span><span style="color:#666">)</span><span style="color:#666">;</span>
- return new AppConfigurationEntry[]{
- new AppConfigurationEntry("com.sun.security.auth.module.Krb5LoginModule",
- AppConfigurationEntry.LoginModuleControlFlag.REQUIRED,
- options),};
- }
-}
-</code></pre>
-<p>Here is how it is used:</p>
-<pre><code>:::Java
-saslGssApiRequest = new SaslGssApiRequest();
-saslGssApiRequest.setLoginModuleConfiguration(new KerberosConfiguration());
-saslGssApiRequest.setMutualAuthentication( true );
+ <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#a2f;font-weight:bold">new</span> AppConfigurationEntry<span style="color:#666">[</span><span style="color:#666">]</span><span style="color:#666">{</span>
+ <span style="color:#a2f;font-weight:bold">new</span> AppConfigurationEntry<span style="color:#666">(</span><span style="color:#b44">"com.sun.security.auth.module.Krb5LoginModule"</span><span style="color:#666">,</span>
+ AppConfigurationEntry<span style="color:#666">.</span><span style="color:#b44">LoginModuleControlFlag</span><span style="color:#666">.</span><span style="color:#b44">REQUIRED</span><span style="color:#666">,</span>
+ options<span style="color:#666">)</span><span style="color:#666">,</span><span style="color:#666">}</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Here is how it is used:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> saslGssApiRequest <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> SaslGssApiRequest<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ saslGssApiRequest<span style="color:#666">.</span><span style="color:#b44">setLoginModuleConfiguration</span><span style="color:#666">(</span><span style="color:#a2f;font-weight:bold">new</span> KerberosConfiguration<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ saslGssApiRequest<span style="color:#666">.</span><span style="color:#b44">setMutualAuthentication</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">true</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-try {
- BindResponse br = ldapNetworkConnection.bind( saslGssApiRequest );
- ldapNetworkConnection.startTls();
-} catch ( LdapException e ) {
- e.printStackTrace();
-}
-</code></pre>
-<p>Note that it is not necessary to set the login context name, since it is only needed to process the configuration file.’</p>
+ <span style="color:#a2f;font-weight:bold">try</span> <span style="color:#666">{</span>
+ BindResponse br <span style="color:#666">=</span> ldapNetworkConnection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> saslGssApiRequest <span style="color:#666">)</span><span style="color:#666">;</span>
+ ldapNetworkConnection<span style="color:#666">.</span><span style="color:#b44">startTls</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span> <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> LdapException e <span style="color:#666">)</span> <span style="color:#666">{</span>
+ e<span style="color:#666">.</span><span style="color:#b44">printStackTrace</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Note that it is not necessary to set the login context name, since it is only needed to process the configuration file.’</p>
<p>Warnings:</p>
<ul>
<li>
@@ -300,39 +287,35 @@ This is not an issue if your authentication comes from key tables or prompts the
</ul>
<h2 id="rebinding">Rebinding</h2>
<p>It’s possible to issue a <strong>Bind</strong> on an already bound connection and the existing LDAP session will be terminated, and replaced by a new LDAP session. In any case, the connection is not dropped when doing so. Note that if the connection was encrypted, it remains encrypted.</p>
-<pre><code>:::Java
-@Test
-public void testRebind() throws Exception
-{
- connection.bind( "uid=admin,ou=system", "secret" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testRebind</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> <span style="color:#b44">"uid=admin,ou=system"</span><span style="color:#666">,</span> <span style="color:#b44">"secret"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- // Now, rebind
- connection.bind( "cn=john doe,dc=example,dc=com", "secret" );
+ <span style="color:#080;font-style:italic">// Now, rebind
+</span><span style="color:#080;font-style:italic"></span> connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> <span style="color:#b44">"cn=john doe,dc=example,dc=com"</span><span style="color:#666">,</span> <span style="color:#b44">"secret"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- assertTrue( connection.isConnected() );
- assertTrue( connection.isAuthenticated() );
-}
-</code></pre>
-<p>If you issue a <em>bind</em> on the same connection with some different credentials, then the existing session will be terminated on the server, and a new one will be created. All the pending requests for the initial session will be lost.</p>
+ assertTrue<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">isConnected</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertTrue<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">isAuthenticated</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>If you issue a <em>bind</em> on the same connection with some different credentials, then the existing session will be terminated on the server, and a new one will be created. All the pending requests for the initial session will be lost.</p>
<h2 id="unbinding">Unbinding</h2>
<p>This is a trivial operation : you just send an <strong>UnbindRequest</strong> to the server, which will invalidate your session.</p>
<p>It’s important to know that when you issue an <strong>Unbind</strong>, the connection is dropped. It’s done like this:</p>
-<pre><code>:::Java
-@Test
-public void testUnbind() throws Exception
-{
- connection.bind( "uid=admin,ou=system", "secret" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testUnbind</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> <span style="color:#b44">"uid=admin,ou=system"</span><span style="color:#666">,</span> <span style="color:#b44">"secret"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- // Now, unbind
- connection.unBind();
- assertFalse( connection.isConnected() );
- assertFalse( connection.isAuthenticated() );
+ <span style="color:#080;font-style:italic">// Now, unbind
+</span><span style="color:#080;font-style:italic"></span> connection<span style="color:#666">.</span><span style="color:#b44">unBind</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ assertFalse<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">isConnected</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertFalse<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">isAuthenticated</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- // And Bind again.
- connection.bind( "uid=admin,ou=system", "secret" );
-}
-</code></pre>
-<p>Last, but not least, if you close the connection, the session also terminates.</p>
+ <span style="color:#080;font-style:italic">// And Bind again.
+</span><span style="color:#080;font-style:italic"></span> connection<span style="color:#666">.</span><span style="color:#b44">bind</span><span style="color:#666">(</span> <span style="color:#b44">"uid=admin,ou=system"</span><span style="color:#666">,</span> <span style="color:#b44">"secret"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Last, but not least, if you close the connection, the session also terminates.</p>
diff --git a/content/api/user-guide/2.3-searching.html b/content/api/user-guide/2.3-searching.html
index 7a25986..0ea52d3 100644
--- a/content/api/user-guide/2.3-searching.html
+++ b/content/api/user-guide/2.3-searching.html
@@ -161,22 +161,20 @@
<p>The idea is to define a search <strong>API</strong> which is easy to use in the simplest cases, but provides all the capability to send complex search requests.</p>
<h2 id="simple-search">Simple search</h2>
<p>Let’s first look at a simple search. To process a search we need a starting point in the tree, a filter, and a scope. Here’s an example:</p>
-<pre><code>:::java
-@Test
-public void testSearch() throws Exception
-{
- EntryCursor cursor = connection.search( "ou=system", "(objectclass=*)", SearchScope.ONELEVEL );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testSearch</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ EntryCursor cursor <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">search</span><span style="color:#666">(</span> <span style="color:#b44">"ou=system"</span><span style="color:#666">,</span> <span style="color:#b44">"(objectclass=*)"</span><span style="color:#666">,</span> SearchScope<span style="color:#666">.</span><span style="color:#b44">ONELEVEL</span> <span style="color:#666">)</span><span style="color:#66 [...]
- for ( Entry entry : cursor )
- {
- assertNotNull( entry );
- System.out.println( entry );
- }
+ <span style="color:#a2f;font-weight:bold">for</span> <span style="color:#666">(</span> Entry entry <span style="color:#666">:</span> cursor <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ assertNotNull<span style="color:#666">(</span> entry <span style="color:#666">)</span><span style="color:#666">;</span>
+ System<span style="color:#666">.</span><span style="color:#b44">out</span><span style="color:#666">.</span><span style="color:#b44">println</span><span style="color:#666">(</span> entry <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
- cursor.close();
-}
-</code></pre>
-<p>In this example, the <em>connection</em> has been previously created. We search for all entries starting at <em>ou=system</em> along with its children, which have an <em>ObjectClass</em> attribute (all the entries have such an attribute, so we should get back all the entries). The scope (<em>ONELEVEL</em>) searches one level under the starting base.</p>
+ cursor<span style="color:#666">.</span><span style="color:#b44">close</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>In this example, the <em>connection</em> has been previously created. We search for all entries starting at <em>ou=system</em> along with its children, which have an <em>ObjectClass</em> attribute (all the entries have such an attribute, so we should get back all the entries). The scope (<em>ONELEVEL</em>) searches one level under the starting base.</p>
<p>A cursor of entries is returned, which can be iterated over. Every call to the <em>getEntry()</em> method returns the next entry in the LDAP result set.</p>
<p>That’s pretty much it!</p>
<p>But this is not really enough, there are many possible options.</p>
@@ -185,24 +183,22 @@ public void testSearch() throws Exception
</blockquote>
<h3 id="searching-using-a-dn">Searching using a DN</h3>
<p>In the previous sample, we used a String to define the starting point of the search. Sometimes it’s convenient to start a search with a DN (i.e. because you got the DN from another operation). In this case, no need to transform the DN into a String before doing your search, simply use the DN!</p>
-<pre><code>:::java
-@Test
-public void testSearchWithDn() throws Exception
-{
- Dn systemDn = new Dn( "ou=system" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testSearchWithDn</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ Dn systemDn <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> Dn<span style="color:#666">(</span> <span style="color:#b44">"ou=system"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- EntryCursor cursor = connection.search( systemDn, "(objectclass=*)", SearchScope.ONELEVEL );
+ EntryCursor cursor <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">search</span><span style="color:#666">(</span> systemDn<span style="color:#666">,</span> <span style="color:#b44">"(objectclass=*)"</span><span style="color:#666">,</span> SearchScope<span style="color:#666">.</span><span style="color:#b44">ONELEVEL</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- for ( Entry entry : cursor )
- {
- assertNotNull( entry );
- System.out.println( entry );
- }
+ <span style="color:#a2f;font-weight:bold">for</span> <span style="color:#666">(</span> Entry entry <span style="color:#666">:</span> cursor <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ assertNotNull<span style="color:#666">(</span> entry <span style="color:#666">)</span><span style="color:#666">;</span>
+ System<span style="color:#666">.</span><span style="color:#b44">out</span><span style="color:#666">.</span><span style="color:#b44">println</span><span style="color:#666">(</span> entry <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
- cursor.close();
-}
-</code></pre>
-<p>This is it!</p>
+ cursor<span style="color:#666">.</span><span style="color:#b44">close</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>This is it!</p>
<h3 id="scope">Scope</h3>
<p>There are three different different scopes you can use to search for data:</p>
<ul>
@@ -253,35 +249,33 @@ public void testSearchWithDn() throws Exception
<li>The controls</li>
</ul>
<p>In both cases, you should fill the <em>SearchRequest</em> message and send it to the server:</p>
-<pre><code>:::Java
-@Test
-public void testSearchWithSearchRequest() throws Exception
-{
- // Create the SearchRequest object
- SearchRequest req = new SearchRequestImpl();
- req.setScope( SearchScope.SUBTREE );
- req.addAttributes( "*" );
- req.setTimeLimit( 0 );
- req.setBase( new Dn( "ou=system" ) );
- req.setFilter( "(cn=user1)" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testSearchWithSearchRequest</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">// Create the SearchRequest object
+</span><span style="color:#080;font-style:italic"></span> SearchRequest req <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> SearchRequestImpl<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ req<span style="color:#666">.</span><span style="color:#b44">setScope</span><span style="color:#666">(</span> SearchScope<span style="color:#666">.</span><span style="color:#b44">SUBTREE</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ req<span style="color:#666">.</span><span style="color:#b44">addAttributes</span><span style="color:#666">(</span> <span style="color:#b44">"*"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ req<span style="color:#666">.</span><span style="color:#b44">setTimeLimit</span><span style="color:#666">(</span> 0 <span style="color:#666">)</span><span style="color:#666">;</span>
+ req<span style="color:#666">.</span><span style="color:#b44">setBase</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">new</span> Dn<span style="color:#666">(</span> <span style="color:#b44">"ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ req<span style="color:#666">.</span><span style="color:#b44">setFilter</span><span style="color:#666">(</span> <span style="color:#b44">"(cn=user1)"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- // Process the request
- SearchCursor searchCursor = connection.search( req );
+ <span style="color:#080;font-style:italic">// Process the request
+</span><span style="color:#080;font-style:italic"></span> SearchCursor searchCursor <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">search</span><span style="color:#666">(</span> req <span style="color:#666">)</span><span style="color:#666">;</span>
- while ( searchCursor.next() )
- {
- Response response = searchCursor.get();
+ <span style="color:#a2f;font-weight:bold">while</span> <span style="color:#666">(</span> searchCursor<span style="color:#666">.</span><span style="color:#b44">next</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ Response response <span style="color:#666">=</span> searchCursor<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
- // process the SearchResultEntry
- if ( response instanceof SearchResultEntry )
- {
- Entry resultEntry = ( ( SearchResultEntry ) response ).getEntry();
- System.out.println( resultEntry );
- }
- }
-}
-</code></pre>
-<p>As we can see, the response is different, we are returned a <em>SearchCursor</em> instance, and we must verify the response type before being able to process it.</p>
+ <span style="color:#080;font-style:italic">// process the SearchResultEntry
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> response <span style="color:#a2f;font-weight:bold">instanceof</span> SearchResultEntry <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ Entry resultEntry <span style="color:#666">=</span> <span style="color:#666">(</span> <span style="color:#666">(</span> SearchResultEntry <span style="color:#666">)</span> response <span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getEntry</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ System<span style="color:#666">.</span><span style="color:#b44">out</span><span style="color:#666">.</span><span style="color:#b44">println</span><span style="color:#666">(</span> resultEntry <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>As we can see, the response is different, we are returned a <em>SearchCursor</em> instance, and we must verify the response type before being able to process it.</p>
diff --git a/content/api/user-guide/2.4-adding.html b/content/api/user-guide/2.4-adding.html
index 00b2f5e..08aa1be 100644
--- a/content/api/user-guide/2.4-adding.html
+++ b/content/api/user-guide/2.4-adding.html
@@ -161,102 +161,94 @@
<h2 id="adding-an-entry">Adding an entry</h2>
<p>Here is the simplest way to add an entry into the server, assuming that the entry is correct. In order to add an entry, you must provide the location where the entry is stored (its <em>Dn</em>) and the list of its <em>Attributes</em> contained within it.</p>
<p>Here are two examples where the entry is injected using <strong>LDIF</strong>:</p>
-<pre><code>:::Java
-@Test
-public void testAddLdif1() throws Exception
-{
- connection.add(
- new DefaultEntry(
- "cn=testadd,ou=system", // The Dn
- "ObjectClass: top",
- "ObjectClass: person",
- "cn: testadd_cn",
- "sn: testadd_sn" ) );
-
- assertTrue( connection.exists( "cn=testadd,ou=system" ) );
-}
-</code></pre>
-<p>In this basic example, we are adding a new entry, created using some <strong>LDIF</strong> formatted parameters, the first one being the entry’s <em>Dn</em>.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testAddLdif1</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span>
+ <span style="color:#a2f;font-weight:bold">new</span> DefaultEntry<span style="color:#666">(</span>
+ <span style="color:#b44">"cn=testadd,ou=system"</span><span style="color:#666">,</span> <span style="color:#080;font-style:italic">// The Dn
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#b44">"ObjectClass: top"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"ObjectClass: person"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"cn: testadd_cn"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"sn: testadd_sn"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ assertTrue<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=testadd,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>In this basic example, we are adding a new entry, created using some <strong>LDIF</strong> formatted parameters, the first one being the entry’s <em>Dn</em>.</p>
<p>Note that it is possible to use some variables in the <strong>LDIF</strong> instead of pure text. Here is the same example, resulting to the same entry being added:</p>
-<pre><code>:::Java
-@Test
-public void testAddLdif2() throws Exception
-{
- String cn = "testadd_cn";
- String sn = "testadd_sn";
-
- connection.add(
- new DefaultEntry(
- "cn=testadd,ou=system", // The Dn
- "ObjectClass: top",
- "ObjectClass: person",
- "cn", cn, // Note : there is no ':' when using a variable
- "sn", sn ) );
-
- assertTrue( connection.exists( "cn=testadd,ou=system" ) );
-}
-</code></pre>
-<p>Down the line, what is important is that the <em>add()</em> operation is taking a full <strong><a href="6.12-entry.html">Entry</a></strong>.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testAddLdif2</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ String cn <span style="color:#666">=</span> <span style="color:#b44">"testadd_cn"</span><span style="color:#666">;</span>
+ String sn <span style="color:#666">=</span> <span style="color:#b44">"testadd_sn"</span><span style="color:#666">;</span>
+
+ connection<span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span>
+ <span style="color:#a2f;font-weight:bold">new</span> DefaultEntry<span style="color:#666">(</span>
+ <span style="color:#b44">"cn=testadd,ou=system"</span><span style="color:#666">,</span> <span style="color:#080;font-style:italic">// The Dn
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#b44">"ObjectClass: top"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"ObjectClass: person"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"cn"</span><span style="color:#666">,</span> cn<span style="color:#666">,</span> <span style="color:#080;font-style:italic">// Note : there is no ':' when using a variable
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#b44">"sn"</span><span style="color:#666">,</span> sn <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ assertTrue<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=testadd,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Down the line, what is important is that the <em>add()</em> operation is taking a full <strong><a href="6.12-entry.html">Entry</a></strong>.</p>
<p>We can also create the <strong><a href="6.12-entry.html">Entry</a></strong> in a different way, which is shown in the following paragraphs.</p>
<h2 id="sending-an-_addrequest_">Sending an <em>AddRequest</em></h2>
<p>When more control is needed we ask the server to add an entry by sending an <strong><a href="">AddRequest</a></strong>, which allows a <strong><a href="">Control</a></strong> to be included in the request.</p>
<p>Here is an example (note that the control is just injected to demonstrate the feature, it doesn’t really do anything special in this example):</p>
-<pre><code>:::java
-@Test
-public void testAddWithControl() throws Exception
-{
- assertFalse( connection.exists( "cn=testadd,ou=system" ) );
-
- Entry entry = new DefaultEntry(
- "cn=testadd,ou=system",
- "ObjectClass : top",
- "ObjectClass : person",
- "cn: testadd_sn",
- "sn: testadd_sn" );
-
- AddRequest addRequest = new AddRequestImpl();
- addRequest.setEntry( entry );
- addRequest.addControl( new ManageDsaITImpl() );
-
- AddResponse response = connection.add( addRequest );
-
- assertNotNull( response );
- assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult().getResultCode() );
-
- assertTrue( connection.exists( "cn=testadd,ou=system" ) );
-}
-</code></pre>
-<h3 id="asynchronous-addition">Asynchronous addition</h3>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testAddWithControl</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertFalse<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=testadd,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ Entry entry <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultEntry<span style="color:#666">(</span>
+ <span style="color:#b44">"cn=testadd,ou=system"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"ObjectClass : top"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"ObjectClass : person"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"cn: testadd_sn"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"sn: testadd_sn"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ AddRequest addRequest <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> AddRequestImpl<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ addRequest<span style="color:#666">.</span><span style="color:#b44">setEntry</span><span style="color:#666">(</span> entry <span style="color:#666">)</span><span style="color:#666">;</span>
+ addRequest<span style="color:#666">.</span><span style="color:#b44">addControl</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">new</span> ManageDsaITImpl<span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ AddResponse response <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">add</span><span style="color:#666">(</span> addRequest <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ assertNotNull<span style="color:#666">(</span> response <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertEquals<span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span><span style="color:#666">,</span> response<span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getResultCode</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#6 [...]
+
+ assertTrue<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=testadd,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h3 id="asynchronous-addition">Asynchronous addition</h3>
<p>Sometimes we need to add an entry, but not check the result immediately. It’s just a matter of calling the <em>addAsync()</em> method, which returns a <em>Future</em> that can be checked somewhere else in the code:</p>
-<pre><code>:::java
-@Test
-public void testAddAsyncLdif() throws Exception
-{
- assertFalse( connection.exists( "cn=testAsyncAdd,ou=system" ) );
-
- Entry entry = new DefaultEntry(
- "cn=testAsyncAdd,ou=system",
- "ObjectClass: top",
- "ObjectClass: person",
- "cn: testAsyncAdd_cn",
- "sn: testAsyncAdd_sn" );
-
- AddRequest addRequest = new AddRequestImpl();
- addRequest.setEntry( entry );
-
- AddFuture addFuture = connection.addAsync( addRequest );
-
- // Here, we can do something else before checking that the entry has been added
-
- AddResponse addResponse = addFuture.get( 1000, TimeUnit.MILLISECONDS );
-
- assertNotNull( addResponse );
- assertEquals( ResultCodeEnum.SUCCESS, addResponse.getLdapResult().getResultCode() );
-
- assertTrue( connection.exists( "cn=testAsyncAdd,ou=system" ) );
-}
-</code></pre>
-<h2 id="do-dont">Do, Don’t</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testAddAsyncLdif</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertFalse<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=testAsyncAdd,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ Entry entry <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultEntry<span style="color:#666">(</span>
+ <span style="color:#b44">"cn=testAsyncAdd,ou=system"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"ObjectClass: top"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"ObjectClass: person"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"cn: testAsyncAdd_cn"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"sn: testAsyncAdd_sn"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ AddRequest addRequest <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> AddRequestImpl<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ addRequest<span style="color:#666">.</span><span style="color:#b44">setEntry</span><span style="color:#666">(</span> entry <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ AddFuture addFuture <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">addAsync</span><span style="color:#666">(</span> addRequest <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#080;font-style:italic">// Here, we can do something else before checking that the entry has been added
+</span><span style="color:#080;font-style:italic"></span>
+ AddResponse addResponse <span style="color:#666">=</span> addFuture<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span> 1000<span style="color:#666">,</span> TimeUnit<span style="color:#666">.</span><span style="color:#b44">MILLISECONDS</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ assertNotNull<span style="color:#666">(</span> addResponse <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertEquals<span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span><span style="color:#666">,</span> addResponse<span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getResultCode</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color [...]
+
+ assertTrue<span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=testAsyncAdd,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h2 id="do-dont">Do, Don’t</h2>
<p>Successfully adding an entry assumes that the entry was correct, i.e. the attributes and values are compatible with the LDAP schema. There are many things checked by the server. Here is a list of constraints that you should respect in order to get your entry injected:</p>
<ul>
<li>The entry must have at least one <strong>Structural</strong> <em>ObjectClass</em></li>
diff --git a/content/api/user-guide/2.5-deleting.html b/content/api/user-guide/2.5-deleting.html
index f04466e..017fc16 100644
--- a/content/api/user-guide/2.5-deleting.html
+++ b/content/api/user-guide/2.5-deleting.html
@@ -160,108 +160,98 @@
<p>Deleting an entry is pretty easy, it just requires the entry’s <em>DN</em>. There is one important thing to understand though, if the entry has children, the operation will fail.</p>
<h2 id="simple-entry-deletion">Simple entry deletion</h2>
<p>We request a deletion by providing the entry’s <em>DN</em>, as in the following example:</p>
-<pre><code>:::Java
-@Test
-public void testDeleteLeafNode() throws Exception
-{
- assertTrue( session.exists( "cn=child1,cn=parent,ou=system" ) );
-
- try
- {
- connection.delete( "cn=child1,cn=parent,ou=system" );
- }
- catch ( LdapException le )
- {
- fail( le.getMessage() );
- }
-
- assertFalse( session.exists( "cn=child1,cn=parent,ou=system" ) );
-}
-</code></pre>
-<p>Trying to delete a parent node would result in an error (NOT_ALLOWED_ON_NON_LEAF) :</p>
-<pre><code>:::Java
-@Test
-public void testDeleteNonLeafFailure() throws Exception
-{
- assertTrue( session.exists( "cn=parent,ou=system" ) );
-
- try
- {
- connection.delete( "cn=parent,ou=system" );
- }
- catch ( LdapException le )
- {
- fail( le.getMessage() );
- }
-
- assertTrue( session.exists( "cn=parent,ou=system" ) );
-}
-</code></pre>
-<h2 id="recursive-deletion-of-entries">Recursive deletion of entries</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testDeleteLeafNode</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertTrue<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=child1,cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">delete</span><span style="color:#666">(</span> <span style="color:#b44">"cn=child1,cn=parent,ou=system"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> LdapException le <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ fail<span style="color:#666">(</span> le<span style="color:#666">.</span><span style="color:#b44">getMessage</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ assertFalse<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=child1,cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><p>Trying to delete a parent node would result in an error (NOT_ALLOWED_ON_NON_LEAF) :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testDeleteNonLeafFailure</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertTrue<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">delete</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> LdapException le <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ fail<span style="color:#666">(</span> le<span style="color:#666">.</span><span style="color:#b44">getMessage</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ assertTrue<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h2 id="recursive-deletion-of-entries">Recursive deletion of entries</h2>
<p>Usually, you can’t delete an entry and all of its children in one operation. However, some servers accept such requests if you send a delete request and a TreeDelete control. This control is a <a href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete-02">draft</a>, which has been implemented by <strong>Microsoft</strong>, <strong>OpenDS</strong>, <strong>OpenDJ</strong>. It will delete all the children and the entry itself. We don’t use a normal <em>delete()</em> me [...]
-<pre><code>:::Java
-@Test
-public void testDeleteWithCascadeControl() throws Exception
-{
- assertTrue( session.exists( "cn=parent,ou=system" ) );
-
-
- try
- {
- connection.deleteTree( "cn=parent,ou=system" );
- }
- catch ( LdapException le )
- {
- fail( le.getMessage() );
- }
-
- assertFalse( session.exists( "cn=parent,ou=system" ) );
-}
-</code></pre>
-<h2 id="sending-a-deleterequest-with-a-control">Sending a DeleteRequest with a control</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testDeleteWithCascadeControl</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertTrue<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+
+ <span style="color:#a2f;font-weight:bold">try</span>
+ <span style="color:#666">{</span>
+ connection<span style="color:#666">.</span><span style="color:#b44">deleteTree</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#a2f;font-weight:bold">catch</span> <span style="color:#666">(</span> LdapException le <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ fail<span style="color:#666">(</span> le<span style="color:#666">.</span><span style="color:#b44">getMessage</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+
+ assertFalse<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h2 id="sending-a-deleterequest-with-a-control">Sending a DeleteRequest with a control</h2>
<p>It’s also possible to associate a <strong>[Control]</strong> with the delete request. In order to do that, you have to create a <em>DelRequest</em> instance. In the following example, we will add the Delete Tree control (this make this call equivalent to the <em>deleteTree()</em> method).</p>
-<pre><code>:::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" ) );
- }
-}
-</code></pre>
-<h2 id="asynchronous-delete">Asynchronous delete</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testDeleteWithControl</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertTrue<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> connection<span style="color:#666">.</span><span style="color:#b44">isControlSupported</span><span style="color:#666">(</span> <span style="color:#b44">"1.2.840.113556.1.4.805"</span> <span style="color:#666">)</span> <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ DeleteRequest deleteRequest <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DeleteRequestImpl<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ deleteRequest<span style="color:#666">.</span><span style="color:#b44">setName</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">new</span> Dn<span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ Control deleteTreeControl <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> OpaqueControl<span style="color:#666">(</span> <span style="color:#b44">"1.2.840.113556.1.4.805"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ deleteRequest<span style="color:#666">.</span><span style="color:#b44">addControl</span><span style="color:#666">(</span> deleteTreeControl <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ DeleteResponse deleteResponse <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">delete</span><span style="color:#666">(</span> deleteRequest <span style="color:#666">)</span><span style="color:#666">;</span>
+
+ assertNotNull<span style="color:#666">(</span> deleteResponse <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertEquals<span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span><span style="color:#666">,</span> deleteResponse<span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getResultCode</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style [...]
+ assertFalse<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+ <span style="color:#666">}</span>
+</code></pre></div><h2 id="asynchronous-delete">Asynchronous delete</h2>
<p>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 <strong>[DeleteRequest]</strong> instance. Here is an example :</p>
-<pre><code>:::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" ) );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@Test</span>
+ <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">testDeleteAsync</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception
+ <span style="color:#666">{</span>
+ assertTrue<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=child,cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- DeleteFuture deleteFuture = connection.deleteAsync( deleteRequest );
+ DeleteRequest deleteRequest <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DeleteRequestImpl<span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span>
+ deleteRequest<span style="color:#666">.</span><span style="color:#b44">setName</span><span style="color:#666">(</span> <span style="color:#a2f;font-weight:bold">new</span> Dn<span style="color:#666">(</span> <span style="color:#b44">"cn=child,cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
- DeleteResponse deleteResponse = deleteFuture.get( 1000, TimeUnit.MILLISECONDS );
+ DeleteFuture deleteFuture <span style="color:#666">=</span> connection<span style="color:#666">.</span><span style="color:#b44">deleteAsync</span><span style="color:#666">(</span> deleteRequest <span style="color:#666">)</span><span style="color:#666">;</span>
- assertNotNull( deleteResponse );
- assertEquals( ResultCodeEnum.SUCCESS, deleteResponse.getLdapResult().getResultCode() );
- assertFalse( session.exists( "cn=child,cn=parent,ou=system" ) );
-}
-</code></pre>
+ DeleteResponse deleteResponse <span style="color:#666">=</span> deleteFuture<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">(</span> 1000<span style="color:#666">,</span> TimeUnit<span style="color:#666">.</span><span style="color:#b44">MILLISECONDS</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertNotNull<span style="color:#666">(</span> deleteResponse <span style="color:#666">)</span><span style="color:#666">;</span>
+ assertEquals<span style="color:#666">(</span> ResultCodeEnum<span style="color:#666">.</span><span style="color:#b44">SUCCESS</span><span style="color:#666">,</span> deleteResponse<span style="color:#666">.</span><span style="color:#b44">getLdapResult</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">getResultCode</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="co [...]
+ assertFalse<span style="color:#666">(</span> session<span style="color:#666">.</span><span style="color:#b44">exists</span><span style="color:#666">(</span> <span style="color:#b44">"cn=child,cn=parent,ou=system"</span> <span style="color:#666">)</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">}</span>
+</code></pre></div>
<div class="nav">
diff --git a/content/api/user-guide/2.6-modifying.html b/content/api/user-guide/2.6-modifying.html
index 1ef3d0b..53d046d 100644
--- a/content/api/user-guide/2.6-modifying.html
+++ b/content/api/user-guide/2.6-modifying.html
@@ -161,10 +161,8 @@
<p>It’s important to understand that many modifications can be applied on a single entry. All those modifications will be applied in an all or none fashion. i.e., if any of the modifications are invalid, none will occur. Also if the server crashes while applying the mods, it’s guaranteed that the entry remains consistent.</p>
<h2 id="how-it-works">How it works?</h2>
<p>Each modification to be applied on an entry is encapsulated into an intermediate class : a <em>Modification</em> instance, which can be created as :</p>
-<pre><code>:::Java
-Modification addedGivenName = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "givenName", "John", "Peter" );
-</code></pre>
-<p>Here the modification instance represents addition of values “John” and “Peter” to the <em>giveName</em> attribute (the <em>givenName</em> attribute can have more than one value).</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> Modification addedGivenName <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName& [...]
+</code></pre></div><p>Here the modification instance represents addition of values “John” and “Peter” to the <em>giveName</em> attribute (the <em>givenName</em> attribute can have more than one value).</p>
<p>There are four different kind of modifications:</p>
<ul>
<li>ModificationOperation.ADD_ATTRIBUTE: add an attribute and values to an entry</li>
@@ -176,101 +174,89 @@ Modification addedGivenName = new DefaultModification( ModificationOperation.ADD
<p>The following two operations completely add or remove attributes.</p>
<h3 id="adding-new-attributes">Adding new attributes</h3>
<p>First of all, let’s learn how to add an attribute. First you must know which entry to modify, which means you must know its Dn. Next, you must create the <em>Modification</em> instance which is applied to the entry. Here is the code that is used to add a <em>givenName</em> attribute to an existing entry :</p>
-<pre><code>:::Java
-...
-Modification addedGivenName = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "givenName",
- "John", "Peter" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ Modification addedGivenName <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"John"</span><span style="color:#666">,</span> <span style="color:#b44">"Peter"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-connection.modify( "uid=Doe,dc=acme,dc=com", addedGivenName );
-...
-</code></pre>
-<h4 id="adding-more-than-one-attribute">Adding more than one attribute</h4>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=Doe,dc=acme,dc=com"</span><span style="color:#666">,</span> addedGivenName <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><h4 id="adding-more-than-one-attribute">Adding more than one attribute</h4>
<p>What if you want to apply more than one modification to the entry ?</p>
<p>Easy : create more than one <em>Modification</em> instance, and add them before calling the <em>modify</em> method :</p>
-<pre><code>:::Java
-...
-Modification addedGivenName = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "givenName",
- "John", "Peter" );
-Modification addedInitials = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "initials",
- "JD" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ Modification addedGivenName <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"John"</span><span style="color:#666">,</span> <span style="color:#b44">"Peter"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ Modification addedInitials <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"initials"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"JD"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-connection.modify( "uid=Doe,dc=acme,dc=com", addedGivenName, addedInitials );
-...
-</code></pre>
-<p>You can add as many <em>Modification</em> instances as needed.</p>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=Doe,dc=acme,dc=com"</span><span style="color:#666">,</span> addedGivenName<span style="color:#666">,</span> addedInitials <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>You can add as many <em>Modification</em> instances as needed.</p>
<h4 id="errors">Errors</h4>
<p>If you try to add an attribute that already exists, you will get an error, like this one :</p>
-<pre><code>:::Java
-...
-Modification addedGivenName = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "givenName",
- "John", "Peter" );
-Modification addedUid = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "uid",
- "Ted" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ Modification addedGivenName <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"John"</span><span style="color:#666">,</span> <span style="color:#b44">"Peter"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
+ Modification addedUid <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"uid"</span><span style="color:#666">,</span>
+ <span style="color:#b44">"Ted"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-connection.modify( "uid=Doe,dc=acme,dc=com", addedGivenName, addedUid );
-...
-</code></pre>
-<p>results in :</p>
-<pre><code>:::Java
-org.apache.directory.api.ldap.model.exception.LdapAttributeInUseException: ATTRIBUTE_OR_VALUE_EXISTS: failed for MessageType : MODIFY_REQUEST
-Message ID : 3
- Modify Request
- Object : 'uid=Doe,dc=acme,dc=com'
- Modification[0]
- Operation : add
- Modification
- givenName: John
- givenName: Peter
- Modification[1]
- Operation : add
- Modification
- uid: Ted
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@13532916: ERR_54 Cannot add a value which is already present : admin
-at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2064)
-at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
-at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
-...
-</code></pre>
-<p>Here, we’ve tried to add the <em>uid</em> attribute that already exists, and the error trace tells us as much.</p>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=Doe,dc=acme,dc=com"</span><span style="color:#666">,</span> addedGivenName<span style="color:#666">,</span> addedUid <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>results in :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44 [...]
+ Message ID <span style="color:#666">:</span> 3
+ Modify Request
+ Object <span style="color:#666">:</span> <span style="">'</span>uid<span style="color:#666">=</span>Doe<span style="color:#666">,</span>dc<span style="color:#666">=</span>acme<span style="color:#666">,</span>dc<span style="color:#666">=</span>com<span style="">'</span>
+ Modification<span style="color:#666">[</span>0<span style="color:#666">]</span>
+ Operation <span style="color:#666">:</span> add
+ Modification
+ givenName<span style="color:#666">:</span> John
+ givenName<span style="color:#666">:</span> Peter
+ Modification<span style="color:#666">[</span>1<span style="color:#666">]</span>
+ Operation <span style="color:#666">:</span> add
+ Modification
+ uid<span style="color:#666">:</span> Ted
+ org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">model</span><span style="color:#666">.</span><span style="color:#b44">message</span><span style="color:#666">.</span><span style="color:#b44">Mod [...]
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">model</span><span style="color:#666">.</span><span style="color:#b44">message</span><span style="color:#666">.</span><span style="color:#b44"> [...]
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">client</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">LdapNetworkConnection</span><span style="color:#666">.</span><span styl [...]
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">client</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">LdapNetworkConnection</span><span style="color:#666">.</span><span styl [...]
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>Here, we’ve tried to add the <em>uid</em> attribute that already exists, and the error trace tells us as much.</p>
<p>Another potential error occurs when adding an attribute type that isn’t allowed on that entry. This occurs because the Entry’s ObjectClass does not allow such an attribute (per the schema), or because the server forbids modification of that entry, due to the ACIs applied on this entry.</p>
<p>Last, but not least, and hopefully this is obvious, the entry <em>must</em> exist prior to modification!</p>
<h3 id="removing-an-attribute">Removing an attribute</h3>
<p>Removing an attribute is actually a bit simpler than adding one, because the values for the attribute don’t need to be specified. Here’s an example where the <em>givenName</em> attribute is removed from an entry:</p>
-<pre><code>:::Java
-...
-Modification deletedGivenName = new DefaultModification( ModificationOperation.REMOVE_ATTRIBUTE, "givenName" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ Modification deletedGivenName <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">REMOVE_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-connection.modify( "uid=Doe,dc=acme,dc=com", adeletedivenName );
-...
-</code></pre>
-<p>Here, we’ve created a modification, specifying the <em>givenName</em> attribute must be removed, and we apply the modification request to the entry.</p>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=Doe,dc=acme,dc=com"</span><span style="color:#666">,</span> adeletedivenName <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>Here, we’ve created a modification, specifying the <em>givenName</em> attribute must be removed, and we apply the modification request to the entry.</p>
<p>Again, more than one attribute may be deleted from an entry. It’s a matter of creating more than one <em>Modification</em> instances and applying them to the entry.</p>
<h4 id="errors-1">Errors</h4>
<p>If you try to delete an attribute that does not exist in the entry, you will get this error:</p>
-<pre><code>:::Java
-org.apache.directory.api.ldap.model.exception.LdapNoSuchAttributeException: NO_SUCH_ATTRIBUTE: failed for MessageType : MODIFY_REQUEST
-Message ID : 3
- Modify Request
- Object : 'uid=admin,ou=system'
- Modification[0]
- Operation : delete
- Modification
- givenName: (null)
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@fbe6f598: ERR_55 Trying to remove an non-existant attribute:
-attributetype ( 2.5.4.42 NAME ( 'givenName' 'gn' )
- DESC 'RFC2256: first name(s) for which the entity is known by'
- SUP name
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
- USAGE userApplications
-)
- at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2057)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
- at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:302)
-</code></pre>
-<p>Here, the entry does not contain the <em>givenName</em> attribute.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44 [...]
+ Message ID <span style="color:#666">:</span> 3
+ Modify Request
+ Object <span style="color:#666">:</span> <span style="">'</span>uid<span style="color:#666">=</span>admin<span style="color:#666">,</span>ou<span style="color:#666">=</span>system<span style="">'</span>
+ Modification<span style="color:#666">[</span>0<span style="color:#666">]</span>
+ Operation <span style="color:#666">:</span> delete
+ Modification
+ givenName<span style="color:#666">:</span> <span style="color:#666">(</span><span style="color:#a2f;font-weight:bold">null</span><span style="color:#666">)</span>
+ org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">model</span><span style="color:#666">.</span><span style="color:#b44">message</span><span style="color:#666">.</span><span style="color:#b44">Mod [...]
+ attributetype <span style="color:#666">(</span> 2<span style="color:#666">.</span><span style="color:#b44">5</span><span style="color:#666">.</span><span style="color:#b44">4</span><span style="color:#666">.</span><span style="color:#b44">42</span> <span style="color:#00a000">NAME</span> <span style="color:#666">(</span> <span style="">'</span>givenName<span style="color:#b44">' '</span>gn<span style="">'</span> <span style="color:#666">)</span>
+ DESC <span style="">'</span>RFC2256<span style="color:#666">:</span> first <span style="color:#00a000">name</span><span style="color:#666">(</span>s<span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">for</span> which the entity is known by<span style="">'</span>
+ SUP name
+ EQUALITY caseIgnoreMatch
+ SUBSTR caseIgnoreSubstringsMatch
+ SYNTAX 1<span style="color:#666">.</span><span style="color:#b44">3</span><span style="color:#666">.</span><span style="color:#b44">6</span><span style="color:#666">.</span><span style="color:#b44">1</span><span style="color:#666">.</span><span style="color:#b44">4</span><span style="color:#666">.</span><span style="color:#b44">1</span><span style="color:#666">.</span><span style="color:#b44">1466</span><span style="color:#666">.</span><span style="color:#b44">115</span><span sty [...]
+ USAGE userApplications
+ <span style="color:#666">)</span>
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">model</span><span style="color:#666">.</span><span style="color:#b44">message</span><span style="color:#666">.</span><span style="color:#b [...]
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">client</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">LdapNetworkConnection</span><span style="color:#666">.</span><span [...]
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">ldap</span><span style="color:#666">.</span><span style="color:#b44">client</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">LdapNetworkConnection</span><span style="color:#666">.</span><span [...]
+ at org<span style="color:#666">.</span><span style="color:#b44">apache</span><span style="color:#666">.</span><span style="color:#b44">directory</span><span style="color:#666">.</span><span style="color:#b44">shared</span><span style="color:#666">.</span><span style="color:#b44">client</span><span style="color:#666">.</span><span style="color:#b44">api</span><span style="color:#666">.</span><span style="color:#b44">operations</span><span style="color:#666">.</span><span style="co [...]
+</code></pre></div><p>Here, the entry does not contain the <em>givenName</em> attribute.</p>
<p>Another potential error is when you trying to remove a mandatory attribute, per the entry’s ObjectClass constraints.</p>
<p>Otherwise, the server might forbid modification of entry due to the ACIs that are applicable to it.</p>
<p>Again the entry <em>must</em> exist prior to performing the modification!</p>
@@ -284,164 +270,151 @@ attributetype ( 2.5.4.42 NAME ( 'givenName' 'gn' )
</ul>
<h3 id="add-values">Add values</h3>
<p>Let’s see with the addition of values. Here, we will assume we have an entry like:</p>
-<pre><code>dn: uid=jDoe,dc=acme,dc=com
-objectClass: person
-objectClass: organizationalPerson
-objectClass: inetOrgPerson
-uid: jDoe
-userPassword: secret
-sn: John Tom Doe
-cn: Doe
-givenName: John
-</code></pre>
-<p>We will add the ‘Tom’ given name to the <em>givenName</em> attribute in this entry :</p>
-<pre><code>:::Java
-...
-Modification addedGivenNameValue = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "givenName", "Tom" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> dn: uid=jDoe,dc=acme,dc=com
+ objectClass: person
+ objectClass: organizationalPerson
+ objectClass: inetOrgPerson
+ uid: jDoe
+ userPassword: secret
+ sn: John Tom Doe
+ cn: Doe
+ givenName: John
+</code></pre></div><p>We will add the ‘Tom’ given name to the <em>givenName</em> attribute in this entry :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ Modification addedGivenNameValue <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">ADD_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span> <span style="color:#b44">"Tom"</span> <span style="color:#666">)</span><span style="color [...]
-connection.modify( "uid=Doe,dc=acme,dc=com", addedGivenNameValue );
-...
-</code></pre>
-<p>The entry now has two values for the <em>giveName</em> attribute :</p>
-<pre><code>dn: uid=jDoe,dc=acme,dc=com
-objectClass: person
-objectClass: organizationalPerson
-objectClass: inetOrgPerson
-uid: jDoe
-userPassword: secret
-sn: John Tom Doe
-cn: Doe
-givenName: John
-givenName: Tom
-</code></pre>
-<h4 id="errors-2">Errors</h4>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=Doe,dc=acme,dc=com"</span><span style="color:#666">,</span> addedGivenNameValue <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>The entry now has two values for the <em>giveName</em> attribute :</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> dn: uid=jDoe,dc=acme,dc=com
+ objectClass: person
+ objectClass: organizationalPerson
+ objectClass: inetOrgPerson
+ uid: jDoe
+ userPassword: secret
+ sn: John Tom Doe
+ cn: Doe
+ givenName: John
+ givenName: Tom
+</code></pre></div><h4 id="errors-2">Errors</h4>
<p>Again, such an operation might fail for many reasons. Let’s see what are the possible errors:</p>
<p>First, if the attribute’s value already exists. You will get an error like this:</p>
-<pre><code>org.apache.directory.api.ldap.model.exception.LdapAttributeInUseException: ATTRIBUTE_OR_VALUE_EXISTS: failed for MessageType :
-MODIFY_REQUEST
-Message ID : 5
- Modify Request
- Object : 'uid=admin,ou=system'
- Modification[0]
- Operation : add
- Modification
- givenName: John
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@867e79fe: ERR_54 Cannot add a value which is already present : John
- at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2064)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
- at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:303)
-</code></pre>
-<p>Note that depending on the attribute’s syntax, you may get this type of error because you entered a value with different casing when the syntax is case-insensitive. Typically, if the attribute contains the value ‘John’ and you try to add the value ‘JOHN’, you will get this error message. Be sure you know what the attribute syntax allows you to do…</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> org.apache.directory.api.ldap.model.exception.LdapAttributeInUseException: ATTRIBUTE_OR_VALUE_EXISTS: failed for MessageType :
+ MODIFY_REQUEST
+ Message ID : 5
+ Modify Request
+ Object : 'uid=admin,ou=system'
+ Modification[0]
+ Operation : add
+ Modification
+ givenName: John
+ org.apache.directory.api.ldap.model.message.ModifyRequestImpl@867e79fe: ERR_54 Cannot add a value which is already present : John
+ at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2064)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
+ at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:303)
+</code></pre></div><p>Note that depending on the attribute’s syntax, you may get this type of error because you entered a value with different casing when the syntax is case-insensitive. Typically, if the attribute contains the value ‘John’ and you try to add the value ‘JOHN’, you will get this error message. Be sure you know what the attribute syntax allows you to do…</p>
<p>Second, if the attribute is single valued, it will not be possible to add another value to it. When this happens you’ll get the following error message:</p>
-<pre><code>org.apache.directory.api.ldap.model.exception.LdapInvalidAttributeValueException: CONSTRAINT_VIOLATION: failed for MessageType : MODIFY_REQUEST
-Message ID : 3
- Modify Request
- Object : 'c=FR,ou=users,ou=system'
- Modification[0]
- Operation : add
- Modification
- c: US
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@cdf2ed2f: ERR_278 More than one value has been provided for the single-valued attribute: c
- at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2127)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
- at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:297)
-</code></pre>
-<p>Third, the ACIs set on the server may not allow updating an entry or its attribute.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> org.apache.directory.api.ldap.model.exception.LdapInvalidAttributeValueException: CONSTRAINT_VIOLATION: failed for MessageType : MODIFY_REQUEST
+ Message ID : 3
+ Modify Request
+ Object : 'c=FR,ou=users,ou=system'
+ Modification[0]
+ Operation : add
+ Modification
+ c: US
+ org.apache.directory.api.ldap.model.message.ModifyRequestImpl@cdf2ed2f: ERR_278 More than one value has been provided for the single-valued attribute: c
+ at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2127)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
+ at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:297)
+</code></pre></div><p>Third, the ACIs set on the server may not allow updating an entry or its attribute.</p>
<h3 id="removing-values">Removing values</h3>
<p>Removing values follow the same pattern. First select the entry, choose its attribute, and list the values to be removed from it. Here is an exemple:</p>
-<pre><code>:::Java
-...
-Modification removedGivenNameValue = new DefaultModification( ModificationOperation.REMOVE_ATTRIBUTE, "givenName", "Tom" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ Modification removedGivenNameValue <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">REMOVE_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName"</span><span style="color:#666">,</span> <span style="color:#b44">"Tom"</span> <span style="color:#666">)</span><span style=" [...]
-connection.modify( "uid=Doe,dc=acme,dc=com", removedGivenNameValue );
-...
-</code></pre>
-<p>The value ‘Tom’ just added should now be removed from the <em>givenName</em> attribute, but the value ‘John’ should still be present.</p>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=Doe,dc=acme,dc=com"</span><span style="color:#666">,</span> removedGivenNameValue <span style="color:#666">)</span><span style="color:#666">;</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><p>The value ‘Tom’ just added should now be removed from the <em>givenName</em> attribute, but the value ‘John’ should still be present.</p>
<p>How do we remove the last value of an attribute? It’s quite simple. The attribute itself must be removed from the entry, if this is allowed (see below).</p>
<h4 id="errors-3">Errors</h4>
<p>There are more potential erros with this operation. Let’s list them all.</p>
<p>First, the value you want to remove does not exist. You will get such an error:</p>
-<pre><code>org.apache.directory.api.ldap.model.exception.LdapNoSuchAttributeException: NO_SUCH_ATTRIBUTE: failed for MessageType :
-MODIFY_REQUEST
-Message ID : 5
- Modify Request
- Object : 'uid=admin,ou=system'
- Modification[0]
- Operation : delete
- Modification
- givenName: Pete
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@39800276: ERR_56 Cannot remove an absent value from attribute : attributetype ( 2.5.4.42 NAME ( 'givenName' 'gn' )
- DESC 'RFC2256: first name(s) for which the entity is known by'
- SUP name
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
- USAGE userApplications
-)
- at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2057)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
- at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:327)
-</code></pre>
-<p>Second, if you try to remove the last value of an attribute which was declared mandatory (in the schema) the following error will occur:</p>
-<pre><code>org.apache.directory.api.ldap.model.exception.LdapSchemaViolationException: OBJECT_CLASS_VIOLATION: failed for MessageType :
-MODIFY_REQUEST
-Message ID : 3
- Modify Request
- Object : 'uid=billyd,ou=users,ou=system'
- Modification[0]
- Operation : delete
- Modification
- sn: billyd
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@5e80ddb2: ERR_279 Required attributes [sn(2.5.4.4)] not found within entry uid=billyd,ou=users,ou=system
- at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2081)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
- at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:314)
-</code></pre>
-<p>Here, we tried to remove the <em>sn</em> attribute’s last value from an entry where it’s a required attribute.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> org.apache.directory.api.ldap.model.exception.LdapNoSuchAttributeException: NO_SUCH_ATTRIBUTE: failed for MessageType :
+ MODIFY_REQUEST
+ Message ID : 5
+ Modify Request
+ Object : 'uid=admin,ou=system'
+ Modification[0]
+ Operation : delete
+ Modification
+ givenName: Pete
+ org.apache.directory.api.ldap.model.message.ModifyRequestImpl@39800276: ERR_56 Cannot remove an absent value from attribute : attributetype ( 2.5.4.42 NAME ( 'givenName' 'gn' )
+ DESC 'RFC2256: first name(s) for which the entity is known by'
+ SUP name
+ EQUALITY caseIgnoreMatch
+ SUBSTR caseIgnoreSubstringsMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
+ USAGE userApplications
+ )
+ at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2057)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
+ at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:327)
+</code></pre></div><p>Second, if you try to remove the last value of an attribute which was declared mandatory (in the schema) the following error will occur:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> org.apache.directory.api.ldap.model.exception.LdapSchemaViolationException: OBJECT_CLASS_VIOLATION: failed for MessageType :
+ MODIFY_REQUEST
+ Message ID : 3
+ Modify Request
+ Object : 'uid=billyd,ou=users,ou=system'
+ Modification[0]
+ Operation : delete
+ Modification
+ sn: billyd
+ org.apache.directory.api.ldap.model.message.ModifyRequestImpl@5e80ddb2: ERR_279 Required attributes [sn(2.5.4.4)] not found within entry uid=billyd,ou=users,ou=system
+ at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2081)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
+ at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:314)
+</code></pre></div><p>Here, we tried to remove the <em>sn</em> attribute’s last value from an entry where it’s a required attribute.</p>
<p>Third, if you try to remove a value which was used as part of the entry’s <em>RDN</em> : which is never allowed. Typically, for the ‘uid=billyd,ou=users,ou=system’ entry, you can’t remove the ‘billyd’ value from the ‘uid’ attribute. This is the error that occurs when such a modification is attempted:</p>
-<pre><code>org.apache.directory.api.ldap.model.exception.LdapSchemaViolationException: NOT_ALLOWED_ON_RDN: failed for MessageType :
-MODIFY_REQUEST
-Message ID : 3
- Modify Request
- Object : 'uid=billyd,ou=users,ou=system'
- Modification[0]
- Operation : delete
- Modification
- uid: billyd
-org.apache.directory.api.ldap.model.message.ModifyRequestImpl@4d149d78: ERR_62 Entry uid=billyd,ou=users,ou=system does not have the uid attributeType, which is part of the RDN";
- at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2081)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
- at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
- at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:314)
-</code></pre>
-<p>There are also classical errors, when ACLs forbid the removal of a value, or the entry doesn’t exist.</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> org.apache.directory.api.ldap.model.exception.LdapSchemaViolationException: NOT_ALLOWED_ON_RDN: failed for MessageType :
+ MODIFY_REQUEST
+ Message ID : 3
+ Modify Request
+ Object : 'uid=billyd,ou=users,ou=system'
+ Modification[0]
+ Operation : delete
+ Modification
+ uid: billyd
+ org.apache.directory.api.ldap.model.message.ModifyRequestImpl@4d149d78: ERR_62 Entry uid=billyd,ou=users,ou=system does not have the uid attributeType, which is part of the RDN";
+ at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2081)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
+ at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:314)
+</code></pre></div><p>There are also classical errors, when ACLs forbid the removal of a value, or the entry doesn’t exist.</p>
<h3 id="replace-values">Replace values</h3>
<p>Here, what we want to do is to replaces all the values from an attribute with some new values. All in all, this is equivalent to first remove the values, then inject the new values, using modifications, except that in some cases, doing so will not work.</p>
<p>An example where such an operation is mandatory is when replacing the values of a mandatory attribute with something different: with two successive operations, that would fail. A replace will work.</p>
<p>What is important here is that the operation simply replace <em>all</em> the existing values* with new ones, removing the previous ones.</p>
<p>Let’s see how it works with a simple example, with an entry containing:</p>
-<pre><code>dn: uid=jDoe,dc=acme,dc=com
-objectClass: person
-objectClass: organizationalPerson
-objectClass: inetOrgPerson
-uid: jDoe
-userPassword: secret
-sn: John Tom Doe
-cn: Doe
-givenName: John
-givenName: Peter
-</code></pre>
-<p>We will try to replace the <em>givenName</em>:</p>
-<pre><code>Modification replaceGn = new DefaultModification( ModificationOperation.REPLACE_ATTRIBUTE, "givenName",
- "Jack" );
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Text" data-lang="Text"> dn: uid=jDoe,dc=acme,dc=com
+ objectClass: person
+ objectClass: organizationalPerson
+ objectClass: inetOrgPerson
+ uid: jDoe
+ userPassword: secret
+ sn: John Tom Doe
+ cn: Doe
+ givenName: John
+ givenName: Peter
+</code></pre></div><p>We will try to replace the <em>givenName</em>:</p>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> Modification replaceGn <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> DefaultModification<span style="color:#666">(</span> ModificationOperation<span style="color:#666">.</span><span style="color:#b44">REPLACE_ATTRIBUTE</span><span style="color:#666">,</span> <span style="color:#b44">"givenName&# [...]
+ <span style="color:#b44">"Jack"</span> <span style="color:#666">)</span><span style="color:#666">;</span>
-connection.modify( "uid=jDoe,dc=acme,dc=com", replaceGn );
-</code></pre>
-<p>The modified entry will have its <em>givenName</em> value replaced by ‘Jack’, the two previous values will have been removed.</p>
+ connection<span style="color:#666">.</span><span style="color:#b44">modify</span><span style="color:#666">(</span> <span style="color:#b44">"uid=jDoe,dc=acme,dc=com"</span><span style="color:#666">,</span> replaceGn <span style="color:#666">)</span><span style="color:#666">;</span>
+</code></pre></div><p>The modified entry will have its <em>givenName</em> value replaced by ‘Jack’, the two previous values will have been removed.</p>
<p>There is one corner case with this operation: creating a <em>Modification</em> instance where the attribute has no value, then the attribute will be removed from the entry.</p>
<h4 id="errors-4">Errors</h4>
<p>You will get the same errors seen in the two previous operation (ADD and REMOVE) for the very same use cases. Here are some more things to watch out for:</p>
diff --git a/content/fortress/coding-standards.html b/content/fortress/coding-standards.html
index 04333bb..435767d 100644
--- a/content/fortress/coding-standards.html
+++ b/content/fortress/coding-standards.html
@@ -138,41 +138,33 @@
<p>IDEA users can import <a href="settings.jar">this file</a> to enfore the code formating.</p>
<h2 id="headers">Headers</h2>
<p>First, you <strong>must</strong> (and this rule accept no exception) use this header in top of all source file, or each file in which you can have comments :</p>
-<pre><code>:::java
-/*
- * 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.
- *
- */
-</code></pre>
-<h3 id="classinterface-headers">Class/Interface headers</h3>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#080;font-style:italic">/*
+</span><span style="color:#080;font-style:italic"> * Licensed to the Apache Software Foundation (ASF) under one
+</span><span style="color:#080;font-style:italic"> * or more contributor license agreements. See the NOTICE file
+</span><span style="color:#080;font-style:italic"> * distributed with this work for additional information
+</span><span style="color:#080;font-style:italic"> * regarding copyright ownership. The ASF licenses this file
+</span><span style="color:#080;font-style:italic"> * to you under the Apache License, Version 2.0 (the
+</span><span style="color:#080;font-style:italic"> * "License"); you may not use this file except in compliance
+</span><span style="color:#080;font-style:italic"> * with the License. You may obtain a copy of the License at
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * http://www.apache.org/licenses/LICENSE-2.0
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> * Unless required by applicable law or agreed to in writing,
+</span><span style="color:#080;font-style:italic"> * software distributed under the License is distributed on an
+</span><span style="color:#080;font-style:italic"> * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+</span><span style="color:#080;font-style:italic"> * KIND, either express or implied. See the License for the
+</span><span style="color:#080;font-style:italic"> * specific language governing permissions and limitations
+</span><span style="color:#080;font-style:italic"> * under the License.
+</span><span style="color:#080;font-style:italic"> *
+</span><span style="color:#080;font-style:italic"> */</span>
+</code></pre></div><h3 id="classinterface-headers">Class/Interface headers</h3>
<p>Each <strong>Class</strong> or <em>Interface</em> should have an header which must contains :</p>
<ul>
-<li>
-<p>A descrption of this class/interface</p>
-</li>
-<li>
-<p>an <em>author</em> tag which should be :</p>
-<pre><code> :::java
- @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
-</code></pre>
-</li>
+<li>A descrption of this class/interface</li>
+<li>an <em>author</em> tag which should be :</li>
</ul>
-<DIV class="note" markdown="1">
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#a2f">@author</span> <span style="color:#666"><</span>a href<span style="color:#666">=</span><span style="color:#b44">"mailto:dev@directory.apache.org"</span><span style="color:#666">></span>Apache Directory Project<span style="color:#666"><</span><span style="color:#666">/</span>a<span style="color:#666"> [...]
+</code></pre></div><DIV class="note" markdown="1">
Thanks to avoid to put your name. The code is not yours, and much more important, but putting ypur name and e-mail, you will intimidate other developper ("Oh, no, I won't mess with this code, it has been developped by XXXX \!") and second, you will receive mail in three years even if you have stopped all commitment on the project (and those who have sent you an e-mail will think that the project's memeber are not responsive...)
</DIV>
<p>If you use <strong>html</strong> tags, remember to escape ‘<’ and ‘>’ characters…</p>
@@ -228,17 +220,15 @@ Thanks to avoid to put your name. The code is not yours, and much more important
<li>‘{’ and ‘}’ must be on the same column</li>
</ul>
<p>This is a code example :</p>
-<pre><code>:::java
-...
-int result = myMethod( param1, param2 )
-
-if ( result > 0 )
-{
- // do something
-}
-...
-</code></pre>
-<h2 id="imports">Imports</h2>
+<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Java" data-lang="Java"> <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+ <span style="color:#0b0;font-weight:bold">int</span> result <span style="color:#666">=</span> myMethod<span style="color:#666">(</span> param1<span style="color:#666">,</span> param2 <span style="color:#666">)</span>
+
+ <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> result <span style="color:#666">></span> 0 <span style="color:#666">)</span>
+ <span style="color:#666">{</span>
+ <span style="color:#080;font-style:italic">// do something
+</span><span style="color:#080;font-style:italic"></span> <span style="color:#666">}</span>
+ <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span>
+</code></pre></div><h2 id="imports">Imports</h2>
<p>Always declare all the classes you import, do not use <strong>x.y.*</strong></p>
<h2 id="what-else-">What else ?</h2>
<p>Well, this was a very short introduction about coding rules. Use commen sense, look at what you see around you when adding some code, ask people about format, if you have a question.</p>
diff --git a/content/index.xml b/content/index.xml
index 0180fa5..917fb6f 100644
--- a/content/index.xml
+++ b/content/index.xml
@@ -611,7 +611,7 @@ Implementation Here is the Control classes and interfaces hierarchy :</descripti
<guid>https://directory.apache.org/api/internal-design-guide/14-extended-operations.html</guid>
<description>14 - Extended Operations Extended Operation is a LDAP message which may content a payload. It is generally sent by the clinet, but the server can send a ExtendedResponse as a response to any operation : the Notice of Disconnection.
Here is the syntax for the extended Operation :
-ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } (the payload is the requestValue or responseValue part, which may be BER encoded).</description>
+ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } (the payload is the requestValue or responseValue part, which may be BER encoded).</description>
</item>
<item>
@@ -1074,7 +1074,7 @@ Kdc server
<guid>https://directory.apache.org/api/user-guide/2.5-deleting.html</guid>
<description>2.5 - Deleting entries Deleting an entry is pretty easy, it just requires the entry&rsquo;s DN. There is one important thing to understand though, if the entry has children, the operation will fail.
Simple entry deletion We request a deletion by providing the entry&rsquo;s DN, as in the following example:
-:::Java @Test public void testDeleteLeafNode() throws Exception { assertTrue( session.exists( &quot;cn=child1,cn=parent,ou=system&quot; ) ); try { connection.delete( &quot;cn=child1,cn=parent,ou=system&quot; ); } catch ( LdapException le ) { fail( le.</description>
+@Test public void testDeleteLeafNode() throws Exception { assertTrue( session.exists( &#34;cn=child1,cn=parent,ou=system&#34; ) ); try { connection.delete( &#34;cn=child1,cn=parent,ou=system&#34; ); } catch ( LdapException le ) { fail( le.</description>
</item>
<item>
@@ -1171,7 +1171,7 @@ Table of content 3.1 - Authentication options 3.2 - Basic authorization 3.3 - H
<guid>https://directory.apache.org/api/internal-design-guide/3-building.html</guid>
<description>3 - Building The project is based on Apache Maven (version 3.x), so you&rsquo;ll have to install it first.
That being said, building the LDAP API is pretty straightforward :
-::: $ mvn clean install Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0 [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: [INFO] [INFO] Apache Directory LDAP API [INFO] Apache Directory LDAP API I18n [INFO] Apache Directory LDAP API Utilities .</description>
+$ mvn clean install Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0 [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: [INFO] [INFO] Apache Directory LDAP API [INFO] Apache Directory LDAP API I18n [INFO] Apache Directory LDAP API Utilities .</description>
</item>
<item>
diff --git a/content/sitemap.xml b/content/sitemap.xml
index 068635a..61a2a9b 100644
--- a/content/sitemap.xml
+++ b/content/sitemap.xml
@@ -289,7 +289,7 @@
<url>
<loc>https://directory.apache.org/api/internal-design-guide/14-extended-operations.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -394,7 +394,7 @@
<url>
<loc>https://directory.apache.org/api/user-guide/2.10-ldap-connection-template.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -404,7 +404,7 @@
<url>
<loc>https://directory.apache.org/api/user-guide/2.2-binding-unbinding.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -484,7 +484,7 @@
<url>
<loc>https://directory.apache.org/api/user-guide/2.3-searching.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -504,7 +504,7 @@
<url>
<loc>https://directory.apache.org/api/user-guide/2.4-adding.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -519,7 +519,7 @@
<url>
<loc>https://directory.apache.org/api/user-guide/2.5-deleting.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -534,7 +534,7 @@
<url>
<loc>https://directory.apache.org/api/user-guide/2.6-modifying.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -569,7 +569,7 @@
<url>
<loc>https://directory.apache.org/api/internal-design-guide/3-building.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -704,7 +704,7 @@
<url>
<loc>https://directory.apache.org/api/internal-design-guide/4-asn1.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -739,7 +739,7 @@
<url>
<loc>https://directory.apache.org/api/internal-design-guide/4.1-asn1-tlv.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -1524,7 +1524,7 @@
<url>
<loc>https://directory.apache.org/api.html</loc>
- <lastmod>2021-05-19T22:54:11+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -1554,7 +1554,7 @@
<url>
<loc>https://directory.apache.org/fortress/coding-standards.html</loc>
- <lastmod>2020-08-08T11:25:14+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>
@@ -1784,7 +1784,7 @@
<url>
<loc>https://directory.apache.org/fortress.html</loc>
- <lastmod>2021-05-18T23:33:49+02:00</lastmod>
+ <lastmod>2021-05-20T04:00:39+02:00</lastmod>
</url>
<url>