/** 
 * 
 * Copyright 2004 Protique Ltd
 * 
 * Licensed 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.activemq.io;
import java.io.DataInput;
import java.io.DataInputStream;
import java.io.DataOutput;
import java.io.DataOutputStream;
import java.io.IOException;
import java.net.DatagramPacket;
import javax.jms.JMSException;
import org.activemq.message.Packet;

/**
 * Represents a strategy of encoding packets on the wire or on disk
 * using some kind of serialization or wire format.
 * <p/>
 * We use a default efficient format
 * for Java to Java communication but other formats to other systems
 * can be used, such as using simple text
 * strings when talking to JavaScript or coming up with other formats for
 * talking to C / C# languages or proprietary messaging systems
 * we wish to interface with at the wire level etc.
 *
 * @version $Revision: 1.1.1.1 $
 */
public interface WireFormat {
    /**
     * The maximum message size supported by the transport
     * If the message is bigger than this size, then the message
     * will be 'chunked' into separate pieces and re-assembled
     * on the consumer
     */
    public static final int DEFAULT_MAXIMUM_MESSAGE_SIZE = 64 * 1024;
    
    /**
     * Reads a packet from the given input stream
     *
     * @param in
     * @return
     * @throws IOException
     */
    public Packet readPacket(DataInput in) throws IOException;

    /**
     * A helper method for working with sockets where the first byte is read
     * first, then the rest of the message is read.
     * <p/>
     * Its common when dealing with sockets to have different timeout semantics
     * until the first non-zero byte is read of a message, after which
     * time a zero timeout is used.
     *
     * @param firstByte the first byte of the packet
     * @param in        the rest of the packet
     * @return
     * @throws IOException
     */
    public Packet readPacket(int firstByte, DataInput in) throws IOException;


    /**
     * Read a packet from a Datagram packet from the given channelID. If the
     * packet is from the same channel ID as it was sent then we have a
     * loop-back so discard the packet
     *
     * @param channelID is the unique channel ID
     * @param dpacket
     * @return the packet read from the datagram or null if it should be
     *         discarded
     * @throws IOException
     */
    public Packet readPacket(String channelID, DatagramPacket dpacket) throws IOException;

    /**
     * Writes the packet to the given output stream
     *
     * @param packet
     * @param out
     * @return a response packet - or null
     * @throws IOException
     * @throws JMSException
     */
    public Packet writePacket(Packet packet, DataOutput out) throws IOException, JMSException;

    /**
     * Writes the given package to a new datagram
     *
     * @param channelID is the unique channel ID
     * @param packet    is the packet to write
     * @return
     * @throws IOException
     * @throws JMSException
     */
    public DatagramPacket writePacket(String channelID, Packet packet) throws IOException, JMSException;

    /**
     * Reads the packet from the given byte[]
     * @param bytes
     * @param offset
     * @param length
     * @return
     * @throws IOException
     */
    public Packet fromBytes(byte[] bytes, int offset, int length) throws IOException;

    /**
     * Reads the packet from the given byte[]
     * @param bytes
     * @return
     * @throws IOException
     */
    public Packet fromBytes(byte[] bytes) throws IOException;

    /**
     * A helper method which converts a packet into a byte array
     *
     * @param packet
     * @return a byte array representing the packet using some wire protocol
     * @throws IOException
     * @throws JMSException
     */
    public byte[] toBytes(Packet packet) throws IOException, JMSException;

    /**
     * Creates a new copy of this wire format so it can be used in another thread/context
     *
     * @return
     */
    public WireFormat copy();
    
    /**
     * Can this wireformat process packets of this version
     * @param version the version number to test
     * @return true if can accept the version
     */
    public boolean canProcessWireFormatVersion(int version);
    
    /**
     * @return the current version of this wire format
     */
    public int getCurrentWireFormatVersion();
    
    /**
     * some transports may register their streams (e.g. Tcp)
     * @param dataOut
     * @param dataIn
     */
    public void registerTransportStreams(DataOutputStream dataOut, DataInputStream dataIn);
    
    /**
     * Some wire formats require a handshake at start-up
     * @throws IOException
     */
    public void initiateClientSideProtocol() throws  IOException;
    
    
    /**
     * Some wire formats require a handshake at start-up
     * @throws IOException
     */
    public void initiateServerSideProtocol() throws  IOException;
    
    
    /**
     * @return Returns the enableCaching.
     */
    public boolean isCachingEnabled();

    /**
     * @param enableCaching The enableCaching to set.
     */
    public void setCachingEnabled(boolean enableCaching);
    
    /**
     * some wire formats will implement their own fragementation
     * @return true unless a wire format supports it's own fragmentation
     */
    public boolean doesSupportMessageFragmentation();
    
    
    /**
     * Some wire formats will not be able to understand compressed messages
     * @return true unless a wire format cannot understand compression
     */
    public boolean doesSupportMessageCompression();
    
}
