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 javax.naming.NamingException;
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 * @return Tells if the wrapped value and the normalized value are the same
054 */
055 boolean isSame();
056
057
058 /**
059 * Sets the wrapped value.
060 *
061 * @param wrapped the value to set: either a String, URI, or a byte[]
062 */
063 void set( T wrapped );
064
065
066 /**
067 * Get the wrapped value.
068 *
069 * @return the wrapped value
070 */
071 T get();
072
073
074 /**
075 * Get the wrapped value as a byte[]. If the original value
076 * is binary, this method will return a copy of the wrapped byte[]
077 *
078 * @return the wrapped value as a byte[]
079 */
080 byte[] getBytes();
081
082
083 /**
084 * Get the wrapped value as a String. If the original value
085 * is binary, this method will return the value as if it was
086 * an UTF-8 encoded String.
087 *
088 * @return the wrapped value as a String
089 */
090 String getString();
091
092
093 /**
094 * Get a reference on the stored value.
095 *
096 * @return a reference on the wrapped value.
097 */
098 T getReference();
099
100
101 /**
102 * Get a copy of the stored value.
103 *
104 * @return a copy of the stored value.
105 */
106 T getCopy();
107
108
109 /**
110 * Reset the value
111 */
112 void clear();
113
114
115 /**
116 * Tells if the value has already be normalized or not.
117 *
118 * @return <code>true</code> if the value has already been normalized.
119 */
120 boolean isNormalized();
121
122
123 /**
124 * Tells if the value is valid. The value must have already been
125 * validated at least once through a call to isValid( SyntaxChecker ).
126 *
127 * @return <code>true</code> if the value is valid
128 */
129 boolean isValid();
130
131
132 /**
133 * Tells if the value is valid wrt a Syntax checker
134 *
135 * @param checker the SyntaxChecker to use to validate the value
136 * @return <code>true</code> if the value is valid
137 * @exception NamingException if the value cannot be validated
138 */
139 boolean isValid( SyntaxChecker checker ) throws NamingException;
140
141
142 /**
143 * Set the normalized flag.
144 *
145 * @param normalized the value : true or false
146 */
147 void setNormalized( boolean normalized );
148
149
150 /**
151 * Gets the normalized (canonical) representation for the wrapped string.
152 * If the wrapped String is null, null is returned, otherwise the normalized
153 * form is returned. If the normalizedValue is null, then this method
154 * will attempt to generate it from the wrapped value: repeated calls to
155 * this method do not unnecessarily normalize the wrapped value. Only changes
156 * to the wrapped value result in attempts to normalize the wrapped value.
157 *
158 * @return gets the normalized value
159 */
160 T getNormalizedValue();
161
162
163 /**
164 * Gets a reference to the the normalized (canonical) representation
165 * for the wrapped value.
166 *
167 * @return gets a reference to the normalized value
168 */
169 T getNormalizedValueReference();
170
171
172 /**
173 * Gets a copy of the the normalized (canonical) representation
174 * for the wrapped value.
175 *
176 * @return gets a copy of the normalized value
177 */
178 T getNormalizedValueCopy();
179
180
181 /**
182 * Normalize the value. In order to use this method, the Value
183 * must be schema aware.
184 *
185 * @exception NamingException if the value cannot be normalized
186 */
187 void normalize() throws NamingException;
188
189
190 /**
191 * Normalize the value. For a client String value, applies the given normalizer.
192 *
193 * It supposes that the client has access to the schema in order to select the
194 * appropriate normalizer.
195 *
196 * @param normalizer the normalizer to apply to the value
197 * @exception NamingException if the value cannot be normalized
198 */
199 void normalize( Normalizer normalizer ) throws NamingException;
200
201
202 /**
203 * Tells if the current value is Binary or String
204 *
205 * @return <code>true</code> if the value is Binary, <code>false</code> otherwise
206 */
207 boolean isBinary();
208
209
210 /**
211 * @return The length of the interned value
212 */
213 int length();
214 }