directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r872029 - in /websites/staging/directory/trunk/content: ./ api/user-guide/6.3-attribute.html
Date Wed, 31 Jul 2013 06:04:35 GMT
Author: buildbot
Date: Wed Jul 31 06:04:35 2013
New Revision: 872029

Log:
Staging update by buildbot for directory

Added:
    websites/staging/directory/trunk/content/api/user-guide/6.3-attribute.html
Modified:
    websites/staging/directory/trunk/content/   (props changed)

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Jul 31 06:04:35 2013
@@ -1 +1 @@
-1508671
+1508734

Added: websites/staging/directory/trunk/content/api/user-guide/6.3-attribute.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/6.3-attribute.html (added)
+++ websites/staging/directory/trunk/content/api/user-guide/6.3-attribute.html Wed Jul 31 06:04:35 2013
@@ -0,0 +1,434 @@
+<!DOCTYPE html>
+<!--
+    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.
+-->
+<html>
+	<head>
+		<title>6.3 - Attribute &mdash; Apache Directory</title>
+		
+	    <link href="./../../css/common.css" rel="stylesheet" type="text/css">
+	    <link href="./../../css/brown.css" rel="stylesheet" type="text/css">
+    
+        
+        <link rel="shortcut icon" href="./../../images/api-icon_16x16.png">
+    
+        <!-- Google Analytics -->
+        <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+        <script type="text/javascript">
+            _uacct = "UA-1358462-1";
+            urchinTracker();
+        </script>
+	</head>
+	<body>
+	    <div id="container">
+            <div id="header">
+                <div id="subProjectsNavBar">
+                    <a href="./../../">
+                        
+                        Apache Directory Project
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../apacheds">
+                        
+                        ApacheDS
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../studio">
+                        
+                        Apache Directory Studio
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../api">
+                        
+                        <STRONG>Apache LDAP API</STRONG>
+                        
+                    </a>
+                </div><!-- subProjectsNavBar -->
+            </div><!-- header -->
+            <div id="content">
+                <div id="leftColumn">
+                    
+<div id="navigation">
+    
+    <h5>Downloads</h5>
+    <ul>
+	    <li><a href="./../../api/downloads.html">Version 1.0.0-M19</a>&nbsp;&nbsp;<IMG src="./../../images/new_badge.gif" alt="" style="margin-bottom:-3px;" border="0"></li>
+        <li><a href="./../../api/download-old-versions.html">Older versions</a></li>
+    </ul>
+    <h5>Getting Started</h5>
+    <ul>
+        <li><a href="./../../api/vision.html">Vision</a></li>
+        <li><a href="./../../api/java-api.html">Java API</a></li>
+        <li><a href="./../../api/groovy-ldap.html">Groovy API</a></li>
+    </ul>
+    <h5>Documentation</h5>
+    <ul>
+	    <li><a href="./../../api/five-minutes-tutorial.html">Five minutes tutorial</a></li>
+	    <li><a href="./../../api/user-guide.html">User Guide</a></li>
+        <li><a href="./../../api/gen-docs/latest/apidocs/">JavaDocs</a></li>
+        <!--li><a href="./../../api/gen-docs/latest/">Generated Reports</a></li-->
+        <li><a href="./../../api/developer-guide.html">Developer Guide</a></li>
+    </ul>
+    
+    
+    <h5>Support</h5>
+    <ul>
+        <li><a href="./../../mailing-lists-and-irc.html">Mailing Lists &amp; IRC</a></li>
+        <li><a href="./../../sources.html">Sources</a></li>
+        <li><a href="./../../issue-tracking.html">Issue Tracking</a></li>
+        <li><a href="./../../commercial-support.html">Commercial Support</a></li>
+    </ul>
+    <h5>Community</h5>
+    <ul>
+        <li><a href="./../../contribute.html">How to Contribute</a></li>
+        <li><a href="./../../team.html">Team</a></li>
+        <li><a href="./../../original-project-proposal.html">Original Project Proposal</a></li>
+        <li><a href="./../../special-thanks.html" class="external-link" rel="nofollow">Special Thanks</a></li>
+    </ul>
+    <h5>About Apache</h5>
+    <ul>
+        <li><a href="http://www.apache.org/">Apache</a></li>
+        <li><a href="http://www.apache.org/licenses/">License</a></li>
+        <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+        <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+        <li><a href="http://www.apache.org/security/">Security</a></li>
+    </ul>
+    <a href="http://ldapcon.org" target="_blank" rel="nofollow"><img src="./../../images/banner-ldapcon-2013.png" alt="LDAPCon 2013" width="167" height="231"></a>
+    
+</div><!-- navigation -->
+
+                </div><!-- leftColumn -->
+                <div id="rightColumn">
+
+
+    <div class="nav">
+        <div class="nav_prev">
+        
+            <a href="6.2-administrative-role.html">6.2 - AdministrativeRole</a>
+		
+        </div>
+        <div class="nav_up">
+        
+            <a href="6-ldap-data-structures.html">6 - LDAP data structures</a>
+		
+        </div>
+        <div class="nav_next">
+        
+            <a href="6.4-attribute-type.html">6.4 - AttributeType</a>
+		
+        </div>
+        <div class="clearfix"></div>
+    </div>
+
+
+<h1 id="63-attribute">6.3 - Attribute</h1>
+<p>The <em>Attribute</em> class is used to store values associated to an <em>AttributeType</em>. An <em>Entry</em> can contain many <em>Attribute{s</em>, but only one of them is mandatory : the <em>ObjectClass</em>  <em>Attribute</em>.</p>
+<p>An <em>Attribute</em> can store zero, one or N values, accordingly to its associated <em>AttributeType</em>, which may allow null values, and which also can forbid muli-values.</p>
+<p>The <em>Attribute</em> has a interned <em>AttributeType</em> which is usually defined using its name. This name is case insensitive, and we can also use the <em>AttributeType</em> <em>OID</em>.</p>
+<h2 id="creating-an-attribute">Creating an Attribute</h2>
+<p>Creating an <em>Attribute</em> is not really a complex operation. Again, we split the API into two categories:</p>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">the</span> <span class="n">schema</span> <span class="n">agnostic</span> <span class="n">_Attributes_</span>
+<span class="o">*</span> <span class="n">the</span> <span class="n">schema</span> <span class="n">aware</span> <span class="n">_Attributes_</span>
+</pre></div>
+
+
+<h3 id="schema-agnostic-attribute">Schema agnostic Attribute</h3>
+<p>If we don't inject a <em>SchemaManager</em> in the constructor, then the <em>Attribute</em> will have no way to control that the <em>AttributeType</em> exists, nor that the <em>Values</em> are valid.</p>
+<p>Let's see how we can create <em>Attributes</em>. Basically, all what you need is to provide the <em>AttributeType</em> as a String, and some <em>Values</em> (it's optional). Here is an example:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; CN &quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>Here, we created an empty <em>Attribute</em>. Note that <em>cn</em> does not allow empty values, but it's not controlled. Also note that the <em>AttributeType</em> is lower cased and trimmed internally.</p>
+<p>Let's see another example, with some values:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; CN &quot;</span><span class="o">,</span> <span class="s">&quot;test&quot;</span><span class="o">,</span> <span class="s">&quot;Test&quot;</span><span class="o">,</span> <span class="s">&quot; test &quot;</span><span class="o">,</span> <span class="s">&quot;test&quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>Here, we create an <em>Attribute</em> with 3 values. We can see that the values are not duplicated (the <em>"test"</em> value is only inserted once) and that values are case sensitive (the <em>"test"</em> and <em>"Test"</em> values are both stored in the <em>Attribute</em>). The values aren't trimmed either, so we can have a <em>"test"</em> and a <em>" test "</em> values stored.</p>
+<p>This is why having a schema aware <em>Attribute</em> is really handy.</p>
+<p>It's possible to store binary values into an <em>Attribute</em> too:</p>
+<div class="codehilite"><pre><span class="kt">byte</span><span class="o">[]</span> <span class="n">bytes1</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[]{</span><span class="mh">0x01</span><span class="o">,</span> <span class="mh">0x02</span><span class="o">};</span>
+<span class="kt">byte</span><span class="o">[]</span> <span class="n">bytes2</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[]{</span><span class="mh">0x03</span><span class="o">,</span> <span class="mh">0x04</span><span class="o">};</span>
+<span class="kt">byte</span><span class="o">[]</span> <span class="n">bytes3</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[]{</span><span class="mh">0x01</span><span class="o">,</span> <span class="mh">0x02</span><span class="o">};</span>
+
+<span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; JpegPhoto &quot;</span><span class="o">,</span> <span class="n">bytes1</span><span class="o">,</span> <span class="n">bytes2</span><span class="o">,</span> <span class="n">bytes3</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>Same here : values are not duplicated.</p>
+<p>Note that it's not allowed to store a mix of binary and String values in an <em>Attribute</em>:</p>
+<div class="codehilite"><pre><span class="kt">byte</span><span class="o">[]</span> <span class="n">bytes1</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[]{</span><span class="mh">0x01</span><span class="o">,</span> <span class="mh">0x02</span><span class="o">};</span>
+
+<span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; JpegPhoto &quot;</span><span class="o">,</span> <span class="s">&quot;test&quot;</span><span class="o">,</span> <span class="n">bytes1</span> <span class="o">);</span> <span class="c1">// Does not compile</span>
+</pre></div>
+
+
+<h3 id="schema-aware-attribute">Schema aware Attribute</h3>
+<p>We can inject a <em>SchemaManager</em> into the <em>Attribute</em> which will allow more control on the values stored into the <em>Attribute</em>. Let's see with some example how it works:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>Here, we created an <em>Attribute</em> with a specific <em>AttributeType</em> ('atCn') and no value. Let's create a new <em>Attribute</em> with some values:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span><span class="o">,</span> <span class="s">&quot;test&quot;</span><span class="o">,</span> <span class="s">&quot;Test&quot;</span><span class="o">,</span> <span class="s">&quot;  test  &quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>The important point here is that the values are all considered equals. The <em>contains</em> method also use the schema to compare the given value with the interned values. Here, with the <em>cn</em> <em>AttributeType</em>, the value is not case sensitive, so <em>"TEST"</em> is considered as an existing value, even if we injected <em>"test"</em>.</p>
+<h2 id="modifying-an-attribute">Modifying an Attribute</h2>
+<p>Now that we created an <em>Attribute</em> we would like to add or remove values from it. This is quite easy. We have a set of methods to add or remove values, and depending on the fact the <em>Attribute</em> is schema aware or not, the added values will be checked. </p>
+<h3 id="adding-some-value">Adding some value</h3>
+<p>Here is an example of some value addition into a schema agnostic <em>Attribute</em>, then the same operation into a schema aware <em>Attribute</em>:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; CN &quot;</span> <span class="o">);</span>
+<span class="n">Attribute</span> <span class="n">attributeSA</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+<span class="c1">// Add two values</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test1&quot;</span><span class="o">,</span> <span class="s">&quot;&quot;</span> <span class="o">);</span>
+
+<span class="c1">// add two values</span>
+<span class="n">attributeSA</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test1&quot;</span><span class="o">,</span> <span class="s">&quot;&quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>We can see that the schema aware <em>Attribute</em> just contains only one value after the operation, as the <em>cn</em> attribute type does not allow empty strings.</p>
+<p>There is one important point to understand : when a schema agnostic <em>Attribute</em> is created, it knows nothing about the type of values it will store. Once the first value is added, the <em>Attribute</em> will be typed accordingly to the first value added. Then, we can't anymore add values if it has not the same type. </p>
+<p>If the <em>Attribute</em> is schema aware, it's quite obvious. You won't be able to add a binary value into a Human Readable <em>Attribute</em>.
+The following test shows that:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; CN &quot;</span> <span class="o">);</span>
+<span class="n">Attribute</span> <span class="n">attributeSA</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+<span class="kt">byte</span><span class="o">[]</span> <span class="n">bytes</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[]{</span><span class="mh">0x01</span><span class="o">,</span> <span class="mh">0x02</span><span class="o">};</span>
+
+
+<span class="c1">// Add two values</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test1&quot;</span> <span class="o">);</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="n">bytes</span> <span class="o">);</span>
+
+<span class="c1">// add two values</span>
+<span class="n">attributeSA</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test1&quot;</span> <span class="o">);</span>
+<span class="n">attributeSA</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="n">bytes</span> <span class="o">);</span>
+</pre></div>
+
+
+<h3 id="removing-some-values">Removing some values</h3>
+<p>Removing a value from an <em>Attribute</em> is a trivial operation. Of course, if the <em>Attribute</em> is schema aware, we will use the <em>AttributeType</em> comparator to check if the value is present in the <em>Attribute</em> or not (the comparator is associated with the attribute equality <em>MatchingRule</em>.</p>
+<p>Here is an example:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot; CN &quot;</span> <span class="o">);</span>
+
+<span class="c1">// Add three values</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test1&quot;</span><span class="o">,</span> <span class="s">&quot;test2&quot;</span><span class="o">,</span> <span class="s">&quot;test3&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Remove 2 of them</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span> <span class="s">&quot;test2&quot;</span><span class="o">,</span> <span class="s">&quot;test3&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Try to remove the last one, using wrong casing</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span> <span class="s">&quot;Test1&quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>And the same example, on a schema aware <em>Attribute</em>. It demonstrates how convenient it is to manipulate such schema aware objects:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+<span class="c1">// Add three values</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Remove 2 of them</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span> <span class="s">&quot;TEST 2&quot;</span><span class="o">,</span> <span class="s">&quot;test   3&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Try to remove the last one, using wrong casing</span>
+<span class="n">attribute</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span> <span class="s">&quot;Test 1&quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<h2 id="attribute-data-access-methods">Attribute data access methods</h2>
+<p>We have a set of methods used to get some information about the <em>Attribute</em>. They are described in this chapter.</p>
+<h3 id="contains">contains()</h3>
+<p>Checks if the given values are present in the <em>Attribute</em>. We can check for more than one value, but in this case, the method returns <em>true</em> only if <strong>all</strong> the values are present.</p>
+<p>If the <em>Attribute</em> is schema aware, then the check uses the <em>AttributeType</em> to compare the given values with the interned values, otherwise, we do a strict comparison.</p>
+<p>Here is an example:</p>
+<div class="codehilite"><pre>    <span class="n">Attribute</span> <span class="n">attribute1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+    <span class="c1">// Add three values</span>
+    <span class="n">attribute1</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span> <span class="o">);</span>
+
+    <span class="n">Attribute</span> <span class="n">attribute2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;cn&quot;</span> <span class="o">);</span>
+
+    <span class="c1">// Add three values</span>
+    <span class="n">attribute2</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span> <span class="o">);</span>
+</pre></div>
+
+
+<h3 id="get">get()</h3>
+<p>Returns the first value from the <em>Attribute</em>. The first value is the one which has been added first. Note that it returns a <em>Value</em> instance.</p>
+<h3 id="getattributetype">getAttributeType()</h3>
+<p>Returns the internal <em>AttributeType</em>, if the <em>Attribute</em> is schema aware.</p>
+<h3 id="getbytes">getBytes()</h3>
+<p>Returns the first value as a <em>byte[]</em>, if the <em>Attribute</em> is not human readable. The user <strong>must</strong> know that the <em>Attribute</em> contains binary values, otherwise he will get an <em>LdapInvalidAttributeValueException</em>.</p>
+<h3 id="getstring">getString()</h3>
+<p>Returns the first value as a <em>String</em>, if the <em>Attribute</em> is  human readable. The user <strong>must</strong> know that the <em>Attribute</em> contains String values, otherwise he will get an <em>LdapInvalidAttributeValueException</em>.</p>
+<h3 id="getid">getId()</h3>
+<p>Returns the <em>AttributeType</em> normalized ID. If the <em>Attribute</em> is schema agnostic, it will be the trimmed and lower cased user provided ID, otherwise it will be the <em>AttributeType</em> OID (not the name).</p>
+<h3 id="getupid">getUpId()</h3>
+<p>Returns the attribute type user provided ID, if the user provided one. Typically, if the <em>Attribute</em> is schema aware, the user might not provide an ID, and in this case, this method will return the <em>AttributeType</em> name, or default to the OID.</p>
+<h3 id="ishumanreadable">isHumanReadable()</h3>
+<p>Tells if the <em>Attribute</em> contains String values or binary values. </p>
+<h2 id="miscellaneous-methods">Miscellaneous methods</h2>
+<p>We also have a set of miscellaneous methods, which are not frequently used. Here they are:</p>
+<h3 id="apply-attributetype">apply( AttributeType )</h3>
+<p>Inject an <em>AttributeType</em> into the <em>Attribute</em>, making it schema aware. It will check that the associated values are valid at the same time, and normalize the values.</p>
+<p>Here is an example of the impact of such a method on an existing attribute :</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;CN&quot;</span><span class="o">,</span> <span class="s">&quot;  A    test&quot;</span> <span class="o">);</span>
+
+<span class="n">attribute</span><span class="o">.</span><span class="na">apply</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>It shows that we can now check that a value is not literately compared, the modified attribute uses the Equality <em>MatchingRule</em> to compare the values.</p>
+<p>Here is another example, where we try to apply an attribute type to some attribute containing an invalid value : it generates an exception, as expected.</p>
+<div class="codehilite"><pre><span class="kt">byte</span><span class="o">[]</span> <span class="n">bytes</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[]{</span><span class="mh">0x01</span><span class="o">,</span> <span class="mh">0x02</span><span class="o">};</span>
+<span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;CN&quot;</span><span class="o">,</span> <span class="n">bytes</span> <span class="o">);</span>
+
+<span class="n">attribute</span><span class="o">.</span><span class="na">apply</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+</pre></div>
+
+
+<h3 id="clear">clear()</h3>
+<p>This method removes all the values from the attribute. The attribute type is not removed. Here is an example demonstrating how it works:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span><span class="o">,</span> <span class="s">&quot;test1&quot;</span><span class="o">,</span> <span class="s">&quot;test2&quot;</span> <span class="o">);</span>
+
+<span class="n">attribute</span><span class="o">.</span><span class="na">clear</span><span class="o">();</span>
+</pre></div>
+
+
+<h3 id="clone">clone()</h3>
+<p>This method create a new instance of an existing attribute. All the values and the attribute type are cloned too and distinct from the original attribute.</p>
+<h3 id="equals-object">equals( Object )</h3>
+<p>Compares two <em>Attributes</em>. All the values are compared and should be present in both attributes. If you compare a schema aware <em>Attribute</em> with a schema agnostic <em>Attribute</em>, they won't be equal.</p>
+<p>Here is a snippet of code demonstrating the <em>equals</em> method:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span><span class="o">,</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span> <span class="o">);</span>
+<span class="n">Attribute</span> <span class="n">attribute2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span><span class="o">,</span> <span class="s">&quot;Test   3&quot;</span><span class="o">,</span> <span class="s">&quot;Test 2  &quot;</span><span class="o">,</span> <span class="s">&quot;Test 1&quot;</span> <span class="o">);</span>
+<span class="n">Attribute</span> <span class="n">attribute3</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;cn&quot;</span><span class="o">,</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span> <span class="o">);</span>
+<span class="n">Attribute</span> <span class="n">attribute4</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;cn&quot;</span><span class="o">,</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Should be true</span>
+<span class="kt">boolean</span> <span class="n">equals</span> <span class="o">=</span> <span class="n">attribute1</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute2</span> <span class="o">);</span>
+<span class="n">equals</span> <span class="o">=</span> <span class="n">attribute3</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute4</span> <span class="o">);</span>
+
+<span class="c1">// Should be false</span>
+<span class="n">equals</span> <span class="o">=</span> <span class="n">attribute1</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute3</span> <span class="o">);</span>
+<span class="n">equals</span> <span class="o">=</span> <span class="n">attribute1</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute4</span> <span class="o">);</span>
+<span class="n">equals</span> <span class="o">=</span> <span class="n">attribute2</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute4</span> <span class="o">);</span>
+
+<span class="c1">// Now, inject an AttrbuteType in one attribute    </span>
+<span class="n">attribute4</span><span class="o">.</span><span class="na">apply</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+<span class="c1">// The previously not equals attributes are now equal :</span>
+<span class="n">equals</span> <span class="o">=</span> <span class="n">attribute1</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute4</span> <span class="o">);</span>
+<span class="n">equals</span> <span class="o">=</span> <span class="n">attribute2</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span> <span class="n">attribute4</span> <span class="o">);</span>
+</pre></div>
+
+
+<h3 id="isinstanceof-attributetype">isInstanceOf( AttributeType )</h3>
+<p>Tells if an <em>Attribute</em> derives from a given <em>AttributeType</em>. It can be useful if you have some schema aware <em>Attribute</em> and if you want to know if its attribute type inherit from an other one. Here is an example of usage:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span><span class="o">,</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Should be true</span>
+<span class="kt">boolean</span> <span class="n">value</span> <span class="o">=</span> <span class="n">attribute</span><span class="o">.</span><span class="na">isInstanceOf</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+</pre></div>
+
+
+<h3 id="isvalid-attributetype">isValid( AttributeType )</h3>
+<p>Checks if the <em>Attribute</em> contains valid data. It's useful if one wants to apply an <em>AttributeType</em> to the <em>Attribute</em>, as the <em>isValid</em> method will tell if it's possible to do so without throwing an exception.</p>
+<p>Here is some code that test the different use cases:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;cn&quot;</span><span class="o">,</span> <span class="s">&quot;\uFFFDtest&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Should be false</span>
+<span class="kt">boolean</span> <span class="n">isValid</span> <span class="o">=</span> <span class="n">attribute1</span><span class="o">.</span><span class="na">isValid</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">)</span> <span class="o">);</span>
+
+<span class="n">Attribute</span> <span class="n">attribute2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;cn&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Should be false, &#39;cn&#39; requires a value</span>
+<span class="n">isValid</span> <span class="o">=</span> <span class="n">attribute2</span><span class="o">.</span><span class="na">isValid</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+<span class="n">Attribute</span> <span class="n">attribute3</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;cn&quot;</span><span class="o">,</span> <span class="s">&quot;test&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Should be true</span>
+<span class="n">value</span> <span class="o">=</span> <span class="n">attribute3</span><span class="o">.</span><span class="na">isValid</span><span class="o">(</span> <span class="n">atCn</span> <span class="o">);</span>
+
+<span class="n">Attribute</span> <span class="n">attribute4</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="s">&quot;dc&quot;</span><span class="o">,</span> <span class="s">&quot;test&quot;</span><span class="o">,</span> <span class="s">&quot;test2&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Should be false, we can&#39;t put more than one value in &#39;dc&#39;</span>
+<span class="n">value</span> <span class="o">=</span> <span class="n">attribute4</span><span class="o">.</span><span class="na">isValid</span><span class="o">(</span> <span class="n">atDc</span> <span class="o">);</span>
+</pre></div>
+
+
+<h3 id="iterator">iterator()</h3>
+<p>A convenient way to iterate on all the <em>Attribute</em> values. It makes it possible to use a <em>for ( Value&lt;?&gt; value : attribute )</em> construct. Here is an example using the iterator:</p>
+<div class="codehilite"><pre><span class="n">Attribute</span> <span class="n">attribute</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultAttribute</span><span class="o">(</span> <span class="n">atCn</span><span class="o">,</span> <span class="s">&quot;test 1&quot;</span><span class="o">,</span> <span class="s">&quot;test 2&quot;</span><span class="o">,</span> <span class="s">&quot;test 3&quot;</span> <span class="o">);</span>
+
+<span class="k">for</span> <span class="o">(</span> <span class="n">Value</span><span class="o">&lt;?&gt;</span> <span class="n">value</span> <span class="o">:</span> <span class="n">attribute</span> <span class="o">)</span>
+<span class="o">{</span>
+    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span> <span class="s">&quot;Value : &quot;</span> <span class="o">+</span> <span class="n">value</span> <span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>This code produces the following output:</p>
+<div class="codehilite"><pre><span class="n">Value</span> <span class="o">:</span> <span class="n">test</span> <span class="mi">1</span>
+<span class="n">Value</span> <span class="o">:</span> <span class="n">test</span> <span class="mi">2</span>
+<span class="n">Value</span> <span class="o">:</span> <span class="n">test</span> <span class="mi">3</span>
+</pre></div>
+
+
+<h3 id="setupid">setUpId()</h3>
+<p>Sets the user provided identifier for the attribute type. If the <em>Attribute</em> is schema agnostic, then the normalized ID will be the given user provided ID lower cased and trimmed. If it's schema aware, it will be used instead of the <em>AttributeType</em> ID.</p>
+<h3 id="size">size()</h3>
+<p>Returns the number of values stored in this <em>Attribute</em></p>
+
+
+    <div class="nav">
+        <div class="nav_prev">
+        
+            <a href="6.2-administrative-role.html">6.2 - AdministrativeRole</a>
+		
+        </div>
+        <div class="nav_up">
+        
+            <a href="6-ldap-data-structures.html">6 - LDAP data structures</a>
+		
+        </div>
+        <div class="nav_next">
+        
+            <a href="6.4-attribute-type.html">6.4 - AttributeType</a>
+		
+        </div>
+        <div class="clearfix"></div>
+    </div>
+
+
+                </div><!-- rightColumn -->
+                <div id="endContent"></div>
+            </div><!-- content -->
+            <div id="footer">&copy; 2003-2012, <a href="http://www.apache.org">The Apache Software Foundation</a> - <a href="./../../privacy-policy.html">Privacy Policy</a><br />
+                Apache Directory, ApacheDS, Apache Directory Server, Apache Directory Studio, Apache LDAP API, Apache Triplesec, Triplesec, Apache, the Apache feather logo, and the Apache Directory project logos are trademarks of The Apache Software Foundation.
+            </div>
+        </div><!-- container -->
+    </body>
+</html>
\ No newline at end of file



Mime
View raw message