ldap/model/src/main/java/org/apache/directory/api/ldap/model/entry/Value.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 *
 */
package org.apache.directory.api.ldap.model.entry;


import java.io.Externalizable;

import org.apache.directory.api.ldap.model.exception.LdapInvalidAttributeValueException;
import org.apache.directory.api.ldap.model.schema.AttributeType;
import org.apache.directory.api.ldap.model.schema.SyntaxChecker;


/**
 * A interface for wrapping attribute values stored into an EntryAttribute. These
 * values can be a String or a byte[].
 *
 * @param <T> The valye type
 * 
 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
 */
public interface Value<T> extends Cloneable, Externalizable, Comparable<Value<T>>
{
    /** A flag used to tell if the value is HR in serialization */
    boolean STRING = true;

    /** A flag used to tell if the value is not HR in serialization */
    boolean BINARY = false;


    /**
     * Clone a Value
     * 
     * @return A cloned value
     */
    Value<T> clone();


    /**
     * Check if the contained value is null or not
     * 
     * @return <code>true</code> if the inner value is null.
     */
    boolean isNull();


    /**
     * Get the associated AttributeType
     * 
     * @return The AttributeType
     */
    AttributeType getAttributeType();


    /**
     * Check if the value is stored into an instance of the given
     * AttributeType, or one of its ascendant.
     * 
     * For instance, if the Value is associated with a CommonName,
     * checking for Name will match.
     * 
     * @param attributeType The AttributeType we are looking at
     * @return <code>true</code> if the value is associated with the given
     * attributeType or one of its ascendant
     */
    boolean isInstanceOf( AttributeType attributeType );


    /**
     * Get the User Provided value. It will return a copy, not a reference.
     *
     * @return a copy of the wrapped value
     */
    T getValue();


    /**
     * Get the wrapped value as a byte[]. If the original value
     * is binary, this method will return a copy of the wrapped byte[]
     *
     * @return the wrapped value as a byte[]
     */
    byte[] getBytes();


    /**
     * Get the user provided value as a String. If the original value
     * is binary, this method will return the value as if it was
     * an UTF-8 encoded String.
     *
     * @return the wrapped value as a String
     */
    String getString();


    /**
     * Gets a reference to the wrapped value.
     * 
     * Warning ! The value is not copied !!!
     *
     * @return a direct handle on the value that is wrapped
     */
    T getReference();


    /**
     * Tells if the value is schema aware or not.
     *
     * @return <code>true</code> if the value is sxhema aware
     */
    boolean isSchemaAware();


    /**
     * Uses the syntaxChecker associated with the attributeType to check if the
     * value is valid.
     * 
     * @param checker the SyntaxChecker to use to validate the value
     * @return <code>true</code> if the value is valid
     * @exception LdapInvalidAttributeValueException if the value cannot be validated
     */
    boolean isValid( SyntaxChecker checker ) throws LdapInvalidAttributeValueException;


    /**
     * Gets the normalized (canonical) representation for the wrapped string.
     * If the wrapped String is null, null is returned, otherwise the normalized
     * form is returned.  If the normalizedValue is null, then this method
     * will attempt to generate it from the wrapped value.
     *
     * @return gets the normalized value
     */
    T getNormValue();


    /**
     * Gets a reference to the the normalized (canonical) representation
     * for the wrapped value.
     *
     * @return gets a reference to the normalized value
     */
    T getNormReference();


    /**
     * Tells if the current value is Human Readable
     * 
     * @return <code>true</code> if the value is a String, <code>false</code> otherwise
     */
    boolean isHumanReadable();


    /**
     * @return The length of the interned value
     */
    int length();
    
    
    /**
     * Apply the AttributeType to this value. Note that this can't be done twice.
     *
     * @param attributeType The AttributeType to apply
     * @throws LdapInvalidAttributeValueException If we have some invalide value
     */
    void apply( AttributeType attributeType ) throws LdapInvalidAttributeValueException;
}