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 }