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