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 */
020package org.apache.directory.shared.ldap.model.entry;
021
022
023import java.io.Externalizable;
024
025import org.apache.directory.shared.ldap.model.exception.LdapInvalidAttributeValueException;
026import org.apache.directory.shared.ldap.model.schema.AttributeType;
027import org.apache.directory.shared.ldap.model.schema.SyntaxChecker;
028
029
030/**
031 * A interface for wrapping attribute values stored into an EntryAttribute. These
032 * values can be a String or a byte[].
033 *
034 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
035 */
036public interface Value<T> extends Cloneable, Externalizable, Comparable<Value<T>>
037{
038    /** Two flags used to tell if the value is HR or not in serialization */
039    public static final boolean STRING = true;
040    public static final boolean BINARY = false;
041
042    /**
043     * Apply an AttributeType to the current Value, normalizing it.
044     *
045     * @param attributeType The AttributeType to apply
046     * @throws LdapInvalidAttributeValueException If the value is not valid accordingly
047     * to the schema
048     */
049    void apply( AttributeType attributeType ) throws LdapInvalidAttributeValueException;
050    
051
052    /**
053     * Clone a Value
054     * 
055     * @return A cloned value
056     */
057    Value<T> clone();
058    
059    
060    /**
061     * Check if the contained value is null or not
062     * 
063     * @return <code>true</code> if the inner value is null.
064     */
065    boolean isNull();
066    
067    
068    /**
069     * Get the associated AttributeType
070     * 
071     * @return The AttributeType
072     */
073    AttributeType getAttributeType();
074
075    
076    /**
077     * Check if the value is stored into an instance of the given 
078     * AttributeType, or one of its ascendant.
079     * 
080     * For instance, if the Value is associated with a CommonName,
081     * checking for Name will match.
082     * 
083     * @param attributeType The AttributeType we are looking at
084     * @return <code>true</code> if the value is associated with the given
085     * attributeType or one of its ascendant
086     */
087    boolean isInstanceOf( AttributeType attributeType );
088
089    
090    /**
091     * Get the wrapped value. It will return a copy, not a reference.
092     *
093     * @return a copy of the wrapped value
094     */
095    T getValue();
096    
097    
098    /**
099     * Get the wrapped value as a byte[]. If the original value
100     * is binary, this method will return a copy of the wrapped byte[]
101     *
102     * @return the wrapped value as a byte[]
103     */
104    byte[] getBytes();
105    
106    
107    /**
108     * Get the wrapped value as a String. If the original value
109     * is binary, this method will return the value as if it was 
110     * an UTF-8 encoded String.
111     *
112     * @return the wrapped value as a String
113     */
114    String getString();
115    
116    
117    /**
118     * Gets a reference to the wrapped value.
119     * 
120     * Warning ! The value is not copied !!!
121     *
122     * @return a direct handle on the value that is wrapped
123     */
124    T getReference();
125    
126    
127    /**
128     * Tells if the value is schema aware or not.
129     *
130     * @return <code>true</code> if the value is sxhema aware
131     */
132    boolean isSchemaAware();
133    
134    
135    /**
136     * Uses the syntaxChecker associated with the attributeType to check if the
137     * value is valid.
138     * 
139     * @param checker the SyntaxChecker to use to validate the value
140     * @return <code>true</code> if the value is valid
141     * @exception LdapInvalidAttributeValueException if the value cannot be validated
142     */
143    boolean isValid( SyntaxChecker checker ) throws LdapInvalidAttributeValueException;
144
145    
146    /**
147     * Gets the normalized (canonical) representation for the wrapped string.
148     * If the wrapped String is null, null is returned, otherwise the normalized
149     * form is returned.  If the normalizedValue is null, then this method
150     * will attempt to generate it from the wrapped value.
151     *
152     * @return gets the normalized value
153     */
154    T getNormValue();
155    
156    
157    /**
158     * Gets a reference to the the normalized (canonical) representation 
159     * for the wrapped value.
160     *
161     * @return gets a reference to the normalized value
162     */
163    T getNormReference();
164
165    
166    /**
167     * Tells if the current value is Human Readable
168     * 
169     * @return <code>true</code> if the value is a String, <code>false</code> otherwise
170     */
171    boolean isHumanReadable();
172    
173    
174    /**
175     * @return The length of the interned value
176     */
177    int length();
178}