001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * You may obtain a copy of the License at 
008     * 
009     * http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS, 
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
014     * See the License for the specific language governing permissions and 
015     * limitations under the License. 
016     * 
017     **/
018    
019    package org.activemq.io;
020    import java.io.DataInput;
021    import java.io.DataInputStream;
022    import java.io.DataOutput;
023    import java.io.DataOutputStream;
024    import java.io.IOException;
025    import java.net.DatagramPacket;
026    import javax.jms.JMSException;
027    import org.activemq.message.Packet;
028    
029    /**
030     * Represents a strategy of encoding packets on the wire or on disk
031     * using some kind of serialization or wire format.
032     * <p/>
033     * We use a default efficient format
034     * for Java to Java communication but other formats to other systems
035     * can be used, such as using simple text
036     * strings when talking to JavaScript or coming up with other formats for
037     * talking to C / C# languages or proprietary messaging systems
038     * we wish to interface with at the wire level etc.
039     *
040     * @version $Revision: 1.1.1.1 $
041     */
042    public interface WireFormat {
043        /**
044         * The maximum message size supported by the transport
045         * If the message is bigger than this size, then the message
046         * will be 'chunked' into separate pieces and re-assembled
047         * on the consumer
048         */
049        public static final int DEFAULT_MAXIMUM_MESSAGE_SIZE = 64 * 1024;
050        
051        /**
052         * Reads a packet from the given input stream
053         *
054         * @param in
055         * @return
056         * @throws IOException
057         */
058        public Packet readPacket(DataInput in) throws IOException;
059    
060        /**
061         * A helper method for working with sockets where the first byte is read
062         * first, then the rest of the message is read.
063         * <p/>
064         * Its common when dealing with sockets to have different timeout semantics
065         * until the first non-zero byte is read of a message, after which
066         * time a zero timeout is used.
067         *
068         * @param firstByte the first byte of the packet
069         * @param in        the rest of the packet
070         * @return
071         * @throws IOException
072         */
073        public Packet readPacket(int firstByte, DataInput in) throws IOException;
074    
075    
076        /**
077         * Read a packet from a Datagram packet from the given channelID. If the
078         * packet is from the same channel ID as it was sent then we have a
079         * loop-back so discard the packet
080         *
081         * @param channelID is the unique channel ID
082         * @param dpacket
083         * @return the packet read from the datagram or null if it should be
084         *         discarded
085         * @throws IOException
086         */
087        public Packet readPacket(String channelID, DatagramPacket dpacket) throws IOException;
088    
089        /**
090         * Writes the packet to the given output stream
091         *
092         * @param packet
093         * @param out
094         * @return a response packet - or null
095         * @throws IOException
096         * @throws JMSException
097         */
098        public Packet writePacket(Packet packet, DataOutput out) throws IOException, JMSException;
099    
100        /**
101         * Writes the given package to a new datagram
102         *
103         * @param channelID is the unique channel ID
104         * @param packet    is the packet to write
105         * @return
106         * @throws IOException
107         * @throws JMSException
108         */
109        public DatagramPacket writePacket(String channelID, Packet packet) throws IOException, JMSException;
110    
111        /**
112         * Reads the packet from the given byte[]
113         * @param bytes
114         * @param offset
115         * @param length
116         * @return
117         * @throws IOException
118         */
119        public Packet fromBytes(byte[] bytes, int offset, int length) throws IOException;
120    
121        /**
122         * Reads the packet from the given byte[]
123         * @param bytes
124         * @return
125         * @throws IOException
126         */
127        public Packet fromBytes(byte[] bytes) throws IOException;
128    
129        /**
130         * A helper method which converts a packet into a byte array
131         *
132         * @param packet
133         * @return a byte array representing the packet using some wire protocol
134         * @throws IOException
135         * @throws JMSException
136         */
137        public byte[] toBytes(Packet packet) throws IOException, JMSException;
138    
139        /**
140         * Creates a new copy of this wire format so it can be used in another thread/context
141         *
142         * @return
143         */
144        public WireFormat copy();
145        
146        /**
147         * Can this wireformat process packets of this version
148         * @param version the version number to test
149         * @return true if can accept the version
150         */
151        public boolean canProcessWireFormatVersion(int version);
152        
153        /**
154         * @return the current version of this wire format
155         */
156        public int getCurrentWireFormatVersion();
157        
158        /**
159         * some transports may register their streams (e.g. Tcp)
160         * @param dataOut
161         * @param dataIn
162         */
163        public void registerTransportStreams(DataOutputStream dataOut, DataInputStream dataIn);
164        
165        /**
166         * Some wire formats require a handshake at start-up
167         * @throws IOException
168         */
169        public void initiateClientSideProtocol() throws  IOException;
170        
171        
172        /**
173         * Some wire formats require a handshake at start-up
174         * @throws IOException
175         */
176        public void initiateServerSideProtocol() throws  IOException;
177        
178        
179        /**
180         * @return Returns the enableCaching.
181         */
182        public boolean isCachingEnabled();
183    
184        /**
185         * @param enableCaching The enableCaching to set.
186         */
187        public void setCachingEnabled(boolean enableCaching);
188        
189        /**
190         * some wire formats will implement their own fragementation
191         * @return true unless a wire format supports it's own fragmentation
192         */
193        public boolean doesSupportMessageFragmentation();
194        
195        
196        /**
197         * Some wire formats will not be able to understand compressed messages
198         * @return true unless a wire format cannot understand compression
199         */
200        public boolean doesSupportMessageCompression();
201        
202    }