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