001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License.
018     *
019     */
020    package org.apache.directory.shared.ldap.entry;
021    
022    
023    import java.io.Externalizable;
024    
025    import org.apache.directory.shared.ldap.exception.LdapException;
026    
027    import org.apache.directory.shared.ldap.schema.Normalizer;
028    import org.apache.directory.shared.ldap.schema.SyntaxChecker;
029    
030    
031    /**
032     * A interface for wrapping attribute values stored into an EntryAttribute. These
033     * values can be a String or a byte[].
034     *
035     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
036     * @version $Rev$, $Date$
037     */
038    public interface Value<T> extends Cloneable, Externalizable, Comparable<Value<T>>
039    {
040        
041        Value<T> clone();
042        
043        
044        /**
045         * Check if the contained value is null or not
046         * 
047         * @return <code>true</code> if the inner value is null.
048         */
049        boolean isNull();
050        
051        
052        /**
053         * Get the wrapped value. It will return a copy, not a reference.
054         *
055         * @return a copy of the wrapped value
056         */
057        T get();
058        
059        
060        /**
061         * Get the wrapped value as a byte[]. If the original value
062         * is binary, this method will return a copy of the wrapped byte[]
063         *
064         * @return the wrapped value as a byte[]
065         */
066        byte[] getBytes();
067        
068        
069        /**
070         * Get the wrapped value as a String. If the original value
071         * is binary, this method will return the value as if it was 
072         * an UTF-8 encoded String.
073         *
074         * @return the wrapped value as a String
075         */
076        String getString();
077        
078        
079        /**
080         * Get a reference on the stored value.
081         *
082         * @return a reference on the wrapped value.
083         */
084        T getReference();
085        
086        
087        /**
088         * Tells if the value has already be normalized or not.
089         *
090         * @return <code>true</code> if the value has already been normalized.
091         */
092        boolean isNormalized();
093        
094        
095        /**
096         * Tells if the value is valid. The value must have already been
097         * validated at least once through a call to isValid( SyntaxChecker ).  
098         * 
099         * @return <code>true</code> if the value is valid
100         */
101        boolean isValid();
102    
103        
104        /**
105         * Tells if the value is valid wrt a Syntax checker
106         * 
107         * @param checker the SyntaxChecker to use to validate the value
108         * @return <code>true</code> if the value is valid
109         * @exception LdapException if the value cannot be validated
110         */
111        boolean isValid( SyntaxChecker checker ) throws LdapException;
112    
113        
114        /**
115         * Set the normalized flag.
116         * 
117         * @param normalized the value : true or false
118         */
119        void setNormalized( boolean normalized );
120    
121        
122        /**
123         * Gets the normalized (canonical) representation for the wrapped string.
124         * If the wrapped String is null, null is returned, otherwise the normalized
125         * form is returned.  If the normalizedValue is null, then this method
126         * will attempt to generate it from the wrapped value: repeated calls to
127         * this method do not unnecessarily normalize the wrapped value.  Only changes
128         * to the wrapped value result in attempts to normalize the wrapped value.
129         *
130         * @return gets the normalized value
131         */
132        T getNormalizedValue();
133        
134        
135        /**
136         * Gets a reference to the the normalized (canonical) representation 
137         * for the wrapped value.
138         *
139         * @return gets a reference to the normalized value
140         */
141        T getNormalizedValueReference();
142    
143        
144        /**
145         * Gets a copy of the the normalized (canonical) representation 
146         * for the wrapped value.
147         *
148         * @return gets a copy of the normalized value
149         */
150        T getNormalizedValueCopy();
151    
152        
153        /**
154         * Normalize the value. In order to use this method, the Value
155         * must be schema aware.
156         * 
157         * @exception LdapException if the value cannot be normalized
158         */
159        void normalize() throws LdapException;
160    
161        
162        /**
163         * Normalize the value. For a client String value, applies the given normalizer.
164         * 
165         * It supposes that the client has access to the schema in order to select the
166         * appropriate normalizer.
167         * 
168         * @param normalizer the normalizer to apply to the value
169         * @exception LdapException if the value cannot be normalized
170         */
171        void normalize( Normalizer normalizer ) throws LdapException;
172        
173        
174        /**
175         * Tells if the current value is Binary or String
176         * 
177         * @return <code>true</code> if the value is Binary, <code>false</code> otherwise
178         */
179        boolean isBinary();
180        
181        
182        /**
183         * @return The length of the interned value
184         */
185        int length();
186    }