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 }