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.mavibot.btree.serializer;
021
022
023import java.io.IOException;
024import java.nio.ByteBuffer;
025import java.util.Comparator;
026
027
028/**
029 * This interface is used by implementations of serializer, deserializer and comparator.
030 * 
031 * @param <T> The type for the element to serialize and compare
032 * 
033 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
034 */
035public interface ElementSerializer<T>
036{
037    /**
038     * Produce the byte[] representation of the element
039     * 
040     * @param key The element to serialize
041     * @return The byte[] containing the serialized element
042     */
043    byte[] serialize( T key );
044
045
046    /**
047     * Deserialize an element from a BufferHandler
048     * 
049     * @param bufferHandler The incoming bufferHandler
050     * @return The deserialized element
051     * @throws IOException If the deserialization failed
052     */
053    T deserialize( BufferHandler bufferHandler ) throws IOException;
054
055
056    /**
057     * Deserialize an element from a ByteBuffer
058     * 
059     * @param buffer The incoming ByteBuffer
060     * @return The deserialized element
061     * @throws IOException If the deserialization failed
062     */
063    T deserialize( ByteBuffer buffer ) throws IOException;
064
065
066    /**
067     * Deserialize an element from a byte[]
068     * 
069     * @param buffer The incoming byte[]
070     * @return The deserialized element
071     * @throws IOException If the deserialization failed
072     */
073    T fromBytes( byte[] buffer ) throws IOException;
074
075
076    /**
077     * Deserialize an element from a byte[]
078     * 
079     * @param buffer The incoming byte[]
080     * @return The deserialized element
081     * @throws IOException If the deserialization failed
082     */
083    T fromBytes( byte[] buffer, int pos ) throws IOException;
084
085
086    /**
087     * Returns the comparison of two types. <br/>
088     * <ul>
089     * <li>If type1 < type2, return -1</li>
090     * <li>If type1 > type2, return 1</li>
091     * <li>If type1 == type2, return 0</li>
092     * </ul>
093     * 
094     * @param type1 The first type to compare 
095     * @param type2 The second type to compare 
096     * @return The comparison result
097     */
098    int compare( T type1, T type2 );
099
100
101    /**
102     * @return the comparator for the used type
103     */
104    Comparator<T> getComparator();
105
106
107    /**
108     * @return the type being serialized
109     */
110    Class<?> getType();
111}