directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: r589264 - in /directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry: ServerStringValue.java ServerValue.java
Date Sun, 28 Oct 2007 03:20:16 GMT
Author: akarasulu
Date: Sat Oct 27 20:20:14 2007
New Revision: 589264

URL: http://svn.apache.org/viewvc?rev=589264&view=rev
Log:
some documentation for ServerValue and ServerStringValue

Modified:
    directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerStringValue.java
    directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerValue.java

Modified: directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerStringValue.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerStringValue.java?rev=589264&r1=589263&r2=589264&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerStringValue.java
(original)
+++ directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerStringValue.java
Sat Oct 27 20:20:14 2007
@@ -20,7 +20,6 @@
 
 
 import org.apache.directory.shared.ldap.entry.StringValue;
-import org.apache.directory.shared.ldap.entry.Value;
 import org.apache.directory.shared.ldap.schema.AttributeType;
 import org.apache.directory.shared.ldap.schema.MatchingRule;
 import org.apache.directory.shared.ldap.schema.Normalizer;
@@ -32,25 +31,38 @@
 
 
 /**
- * A server side value which is also a StringValue.
+ * A server side schema aware wrapper around a String value.  This value
+ * wrapper uses schema information to syntax check values, and to compare
+ * them for equality and ordering.  It caches results and invalidates
+ * them when the wrapped value changes.
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
  */
 public class ServerStringValue extends StringValue implements ServerValue<String>
 {
+    /** logger for reporting errors that might not be handled properly upstream */
     private static final Logger LOG = LoggerFactory.getLogger( ServerStringValue.class );
 
-    private String normalizedValue;
-
-    // use this to lookup the attributeType when deserializing
+    /** used to dynamically lookup the attributeType when/if deserializing */
     @SuppressWarnings ( { "UnusedDeclaration" } )
     private final String oid;
 
-    // do not serialize the schema entity graph associated with the type
+    /** reference to the attributeType which is not serialized */
     private transient AttributeType attributeType;
 
+    /** the canonical representation of the wrapped value */
+    private transient String normalizedValue;
+
+    /** cached results of the isValid() method call */
+    private transient Boolean valid;
+
 
+    /**
+     * Creates a ServerStringValue without an initial wrapped value.
+     *
+     * @param attributeType the schema type associated with this ServerStringValue
+     */
     public ServerStringValue( AttributeType attributeType )
     {
         if ( attributeType == null )
@@ -62,6 +74,12 @@
     }
 
 
+    /**
+     * Creates a ServerStringValue with an initial wrapped value.
+     *
+     * @param attributeType the schema type associated with this ServerStringValue
+     * @param wrapped the value to wrap which can be null
+     */
     public ServerStringValue( AttributeType attributeType, String wrapped )
     {
         if ( attributeType == null )
@@ -74,6 +92,42 @@
     }
 
 
+    /**
+     * The normalizedValue will be invalidated (set to null) when a new different
+     * wrapper value is set.
+     *
+     * @see ServerValue#set(Object)
+     */
+    public final void set( String wrapped )
+    {
+        // Why should we invalidate the normalized value if it's we're setting the
+        // wrapper to it's current value?
+        if ( wrapped.equals( get() ) )
+        {
+            return;
+        }
+
+        normalizedValue = null;
+        valid = null;
+        super.set( wrapped );
+    }
+
+
+    // -----------------------------------------------------------------------
+    // ServerValue<String> Methods
+    // -----------------------------------------------------------------------
+
+
+    /**
+     * Gets the normalized (cannonical) representation for the wrapped string.
+     * If the wrapped String is null, null is returned, otherwise the normalized
+     * form is returned.  If no the normalizedValue is null, then this method
+     * will attempt to generate it from the wrapped value: repeated calls to
+     * this method do not unnecessarily normalize the wrapped value.  Only changes
+     * to the wrapped value result in attempts to normalize the wrapped value.
+     *
+     * @see ServerValue#getNormalizedValue()
+     */
     public String getNormalizedValue() throws NamingException
     {
         if ( get() == null )
@@ -99,79 +153,76 @@
     }
 
 
-    public final void set( String wrapped )
-    {
-        normalizedValue = null;
-        super.set( wrapped );
-    }
-
-
+    /**
+     * Uses the syntaxChecker associated with the attributeType to check if the
+     * value is valid.  Repeated calls to this method do not attempt to re-check
+     * the syntax of the wrapped value every time if the wrapped value does not
+     * change. Syntax checks only result on the first check, and when the wrapped
+     * value changes.
+     *
+     * @see ServerValue#isValid()
+     */
     public final boolean isValid() throws NamingException
     {
-        return attributeType.getSyntax().getSyntaxChecker().isValidSyntax( get() );
+        if ( valid != null )
+        {
+            return valid;
+        }
+
+        valid = attributeType.getSyntax().getSyntaxChecker().isValidSyntax( get() );
+        return valid;
     }
 
 
+    /**
+     * @see ServerValue#compareTo(ServerValue)
+     * @throws IllegalStateException on failures to extract the comparator, or the
+     * normalizers needed to perform the required comparisons based on the schema
+     */
     public int compareTo( ServerValue<String> value )
     {
-        try
+        if ( value == null && get() == null )
         {
-            //noinspection unchecked
-            return getComparator().compare( getNormalizedValue(), value.getNormalizedValue()
);
+            return 0;
         }
-        catch ( Exception e )
+
+        if ( value != null && get() == null )
         {
-            throw new IllegalStateException( "Failed to normalize values.", e );
+            if ( value.get() == null )
+            {
+                return 0;
+            }
+            return -1;
         }
-    }
-
-
-    private MatchingRule getMatchingRule() throws NamingException
-    {
-        MatchingRule mr = attributeType.getEquality();
 
-        if ( mr == null )
+        if ( value == null )
         {
-            mr = attributeType.getOrdering();
+            return 1;
         }
 
-        if ( mr == null )
+        try
         {
-            mr = attributeType.getSubstr();
+            //noinspection unchecked
+            return getComparator().compare( getNormalizedValue(), value.getNormalizedValue()
);
         }
-
-        return mr;
-    }
-
-
-    private Normalizer getNormalizer() throws NamingException
-    {
-        MatchingRule mr = getMatchingRule();
-
-        if ( mr == null )
+        catch ( NamingException e )
         {
-            return null;
+            String msg = "Failed to compare normalized values for " + get() + " and " + value.get();
+            LOG.error( msg, e );
+            throw new IllegalStateException( msg, e );
         }
-
-        return mr.getNormalizer();
     }
 
 
-    private Comparator getComparator() throws NamingException
-    {
-        MatchingRule mr = getMatchingRule();
-
-        if ( mr == null )
-        {
-            return null;
-        }
-
-        return mr.getComparator();
-    }
+    // -----------------------------------------------------------------------
+    // Object Methods
+    // -----------------------------------------------------------------------
 
 
     /**
      * @see Object#hashCode()
+     * @throws IllegalStateException on failures to extract the comparator, or the
+     * normalizers needed to perform the required comparisons based on the schema
      */
     public int hashCode()
     {
@@ -188,57 +239,20 @@
         }
         catch ( NamingException e )
         {
-            LOG.warn( "Failed to get normalized value while trying to get hashCode: {}",
toString() , e );
-
-            // recover by using non-normalized values
-            return get().hashCode();
-        }
-    }
-
-
-    public int compareTo( Value<String> value )
-    {
-        if ( value == null && get() == null )
-        {
-            return 0;
-        }
-
-        if ( value != null && get() == null )
-        {
-            if ( value.get() == null )
-            {
-                return 0;
-            }
-            return -1;
-        }
-
-        if ( value == null )
-        {
-            return 1;
-        }
-
-
-        try
-        {
-            if ( value instanceof ServerStringValue )
-            {
-                //noinspection unchecked
-                return getComparator().compare( getNormalizedValue(),
-                        ( ( ServerStringValue ) value ).getNormalizedValue() );
-            }
-
-            //noinspection unchecked
-            return getComparator().compare( getNormalizedValue(), value.get() );
-        }
-        catch ( NamingException e )
-        {
-            throw new IllegalStateException( "Normalization failed when it should have succeeded",
e );
+            String msg = "Failed to normalize \"" + get() + "\" while trying to get hashCode()";
+            LOG.error( msg, e );
+            throw new IllegalStateException( msg, e );
         }
     }
 
 
     /**
-     * @see Object#equals(Object)
+     * Checks to see if this ServerStringValue equals the supplied object.
+     *
+     * This equals implementation overrides the StringValue implementation which
+     * is not schema aware.
+     * @throws IllegalStateException on failures to extract the comparator, or the
+     * normalizers needed to perform the required comparisons based on the schema
      */
     public boolean equals( Object obj )
     {
@@ -277,13 +291,82 @@
         }
         catch ( NamingException e )
         {
-            // 1st this is a warning because we're recovering from it and secondly
-            // we build big string since waste is not an issue when exception handling
-            LOG.warn( "Failed to get normalized value while trying to compare StringValues:
"
-                    + toString() + " and " + other.toString() , e );
+            String msg = "Failed to normalize while testing for equality on String values:
\"";
+            msg += get() + "\"" + " and \"" + other.get() + "\"" ;
+            LOG.error( msg, e );
+            throw new IllegalStateException( msg, e );
+        }
+    }
+
 
-            // recover by comparing non-normalized values
-            return get().equals( other.get() );
+    // -----------------------------------------------------------------------
+    // Private Helper Methods (might be put into abstract base class)
+    // -----------------------------------------------------------------------
+
+
+    /**
+     * Find a matchingRule to use for normalization and comparison.  If an equality
+     * matchingRule cannot be found it checks to see if other matchingRules are
+     * available: SUBSTR, and ORDERING.  If a matchingRule cannot be found null is
+     * returned.
+     *
+     * @return a matchingRule or null if one cannot be found for the attributeType
+     * @throws NamingException if resolution of schema entities fail
+     */
+    private MatchingRule getMatchingRule() throws NamingException
+    {
+        MatchingRule mr = attributeType.getEquality();
+
+        if ( mr == null )
+        {
+            mr = attributeType.getOrdering();
+        }
+
+        if ( mr == null )
+        {
+            mr = attributeType.getSubstr();
         }
+
+        return mr;
+    }
+
+
+    /**
+     * Gets a normalizer using getMatchingRule() to resolve the matchingRule
+     * that the normalizer is extracted from.
+     *
+     * @return a normalizer associated with the attributeType or null if one cannot be found
+     * @throws NamingException if resolution of schema entities fail
+     */
+    private Normalizer getNormalizer() throws NamingException
+    {
+        MatchingRule mr = getMatchingRule();
+
+        if ( mr == null )
+        {
+            return null;
+        }
+
+        return mr.getNormalizer();
+    }
+
+
+    /**
+     * Gets a comparator using getMatchingRule() to resolve the matching
+     * that the comparator is extracted from.
+     *
+     * @return a comparator associated with the attributeType or null if one cannot be found
+     * @throws NamingException if resolution of schema entities fail
+     */
+    private Comparator getComparator() throws NamingException
+    {
+        MatchingRule mr = getMatchingRule();
+
+        if ( mr == null )
+        {
+            return null;
+        }
+
+        return mr.getComparator();
     }
 }

Modified: directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerValue.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerValue.java?rev=589264&r1=589263&r2=589264&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerValue.java
(original)
+++ directory/apacheds/branches/bigbang/core-entry/src/main/java/org/apache/directory/server/core/entry/ServerValue.java
Sat Oct 27 20:20:14 2007
@@ -25,7 +25,28 @@
 
 
 /**
- * Document me!
+ * A server side entry value wrapper.  Server side value wrappers are
+ * schema aware, knowing the attributeType of the attributes which contain them,
+ * and hence they are capable of things like:
+ *
+ * <ul>
+ *   <li>producing, caching and invalidate normalized versions of their wrapped values</li>
+ *   <li>
+ *     determining if the wrapped value complies with the syntax of their associated
+ *     attributeType
+ *   </li>
+ *   <li>
+ *     comparing wrapped values on the basis of their cannonical representation which
+ *     utilizes the matchingRules of the attributeType associated with these server
+ *     side values
+ *   </li>
+ * </ul>
+ *
+ * These characteristics have a major impact on how these objects are treated in
+ * containers: compared (ordered), hashed, added, removed, and looked up. Furthermore
+ * a great advantage is gained in simplifying code which must deal with values based
+ * on their associated schema.  A large portion of the value managing code which is
+ * setup to compare and test values can now be avoided.
  *
  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
  * @version $Rev$, $Date$
@@ -33,15 +54,37 @@
 public interface ServerValue<T> extends Value<T>
 {
     /**
-     * Gets the normalized representation for the wrapped value of this ServerValue
-     * wrapper. Implementations
+     * Gets the normalized representation for the wrapped value of this
+     * ServerValue wrapper. Implementations will most likely leverage the
+     * attributeType this value is associated with to determine how to
+     * properly normalize the wrapped value.
      *
-     * @return the normalized wrapped value
-     * @throws NamingException if resolution of needed schema entities fails or normalization
fails
+     * @return the normalized version of the wrapped value
+     * @throws NamingException if schema entity resolution fails or normalization fails
      */
     T getNormalizedValue() throws NamingException;
 
+
+    /**
+     * Checks to see if this ServerValue is valid according to the syntax
+     * of the ServerAttribute which contains it.
+     *
+     * @return true if valid according to syntax, false otherwise
+     * @throws NamingException if schema entity resolution fails or the syntaxChecker fails
+     */
     boolean isValid() throws NamingException;
 
+
+    /**
+     * Compares two ServerValue objects for ordering based on the matchingRules
+     * associated with the ServerAttribute containing this ServerValue.
+     * Implementations should be using the normalized versions of the wrapped
+     * value when conducting comparisons.
+     *
+     * @param value the ServerValue object to compare this ServerValue to
+     * @return 0 if the objects are equivalent according to equals(), 1 or greater
+     * if this ServerValue is greater than the supplied ServerValue, -1 or lesser
+     * if this ServerValue is less than the supplied ServerValue.
+     */
     int compareTo( ServerValue<T> value );
 }



Mime
View raw message