From decfd77364e211bc8f8784e15f54e06a79e16675 Mon Sep 17 00:00:00 2001 From: Rupert Smith Date: Tue, 15 May 2007 16:32:10 +0000 Subject: Merged revisions 538109 via svnmerge from https://svn.apache.org/repos/asf/incubator/qpid/branches/M2 ........ r538109 | rupertlssmith | 2007-05-15 10:48:16 +0100 (Tue, 15 May 2007) | 1 line More Javadocing. ........ git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@538247 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/qpid/codec/AMQCodecFactory.java | 36 +++++++++-- .../java/org/apache/qpid/codec/AMQDecoder.java | 74 ++++++++++++++++++++-- .../java/org/apache/qpid/codec/AMQEncoder.java | 37 +++++++++-- .../java/org/apache/qpid/protocol/AMQConstant.java | 2 +- 4 files changed, 131 insertions(+), 18 deletions(-) (limited to 'java/common/src') diff --git a/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java b/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java index d7f1edbc30..4e3a46eb90 100644 --- a/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java +++ b/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java @@ -7,9 +7,9 @@ * 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 @@ -24,28 +24,52 @@ import org.apache.mina.filter.codec.ProtocolCodecFactory; import org.apache.mina.filter.codec.ProtocolDecoder; import org.apache.mina.filter.codec.ProtocolEncoder; +/** + * AMQCodecFactory is a Mina codec factory. It supplies the encoders and decoders need to read and write the bytes to + * the wire. + * + *

+ *
CRC Card
Responsibilities Collaborations. + *
Supply the protocol encoder. {@link AMQEncoder} + *
Supply the protocol decoder. {@link AMQDecoder} + *
+ */ public class AMQCodecFactory implements ProtocolCodecFactory { + /** Holds the protocol encoder. */ private AMQEncoder _encoder = new AMQEncoder(); + /** Holds the protocol decoder. */ private AMQDecoder _frameDecoder; /** - * @param expectProtocolInitiation true if the first frame received is going to be - * a protocol initiation frame, false if it is going to be a standard AMQ data block. - * The former case is used for the broker, which always expects to received the - * protocol initiation first from a newly connected client. + * Creates a new codec factory, specifiying whether it is expected that the first frame of data should be an + * initiation. This is the case for the broker, which always expects to received the protocol initiation on a newly + * connected client. + * + * @param expectProtocolInitiation true if the first frame received is going to be a protocol initiation + * frame, false if it is going to be a standard AMQ data block. */ public AMQCodecFactory(boolean expectProtocolInitiation) { _frameDecoder = new AMQDecoder(expectProtocolInitiation); } + /** + * Gets the AMQP encoder. + * + * @return The AMQP encoder. + */ public ProtocolEncoder getEncoder() { return _encoder; } + /** + * Gets the AMQP decoder. + * + * @return The AMQP decoder. + */ public ProtocolDecoder getDecoder() { return _frameDecoder; diff --git a/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java b/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java index bb981a242f..02ae3cb089 100644 --- a/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java +++ b/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java @@ -7,9 +7,9 @@ * 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 @@ -24,28 +24,61 @@ import org.apache.mina.common.ByteBuffer; import org.apache.mina.common.IoSession; import org.apache.mina.filter.codec.CumulativeProtocolDecoder; import org.apache.mina.filter.codec.ProtocolDecoderOutput; + import org.apache.qpid.framing.AMQDataBlockDecoder; import org.apache.qpid.framing.ProtocolInitiation; /** - * There is one instance of this class per session. Any changes or configuration done - * at run time to the encoders or decoders only affects decoding/encoding of the - * protocol session data to which is it bound. + * AMQDecoder delegates the decoding of AMQP either to a data block decoder, or in the case of new connections, to a + * protocol initiation decoder. It is a cumulative decoder, which means that it can accumulate data to decode in the + * buffer until there is enough data to decode. + * + *

One instance of this class is created per session, so any changes or configuration done at run time to the + * decoder will only affect decoding of the protocol session data to which is it bound. * + *

+ *
CRC Card
Responsibilities Collaborations + *
Delegate protocol initiation to its decoder. {@link ProtocolInitiation.Decoder} + *
Delegate AMQP data to its decoder. {@link AMQDataBlockDecoder} + *
Accept notification that protocol initiation has completed. + *
+ * + * @todo If protocol initiation decoder not needed, then don't create it. Probably not a big deal, but it adds to the + * per-session overhead. */ public class AMQDecoder extends CumulativeProtocolDecoder { + /** Holds the 'normal' AMQP data decoder. */ private AMQDataBlockDecoder _dataBlockDecoder = new AMQDataBlockDecoder(); + /** Holds the protocol initiation decoder. */ private ProtocolInitiation.Decoder _piDecoder = new ProtocolInitiation.Decoder(); + /** Flag to indicate whether this decoder needs to handle protocol initiation. */ private boolean _expectProtocolInitiation; + /** + * Creates a new AMQP decoder. + * + * @param expectProtocolInitiation true if this decoder needs to handle protocol initiation. + */ public AMQDecoder(boolean expectProtocolInitiation) { _expectProtocolInitiation = expectProtocolInitiation; } + /** + * Delegates decoding AMQP from the data buffer that Mina has retrieved from the wire, to the data or protocol + * intiation decoders. + * + * @param session The Mina session. + * @param in The raw byte buffer. + * @param out The Mina object output gatherer to write decoded objects to. + * + * @return true if the data was decoded, false if more is needed and the data should accumulate. + * + * @throws Exception If the data cannot be decoded for any reason. + */ protected boolean doDecode(IoSession session, ByteBuffer in, ProtocolDecoderOutput out) throws Exception { if (_expectProtocolInitiation) @@ -58,6 +91,17 @@ public class AMQDecoder extends CumulativeProtocolDecoder } } + /** + * Decodes AMQP data, delegating the decoding to an {@link AMQDataBlockDecoder}. + * + * @param session The Mina session. + * @param in The raw byte buffer. + * @param out The Mina object output gatherer to write decoded objects to. + * + * @return true if the data was decoded, false if more is needed and the data should accumulate. + * + * @throws Exception If the data cannot be decoded for any reason. + */ protected boolean doDecodeDataBlock(IoSession session, ByteBuffer in, ProtocolDecoderOutput out) throws Exception { int pos = in.position(); @@ -72,10 +116,22 @@ public class AMQDecoder extends CumulativeProtocolDecoder else { _dataBlockDecoder.decode(session, in, out); + return true; } } + /** + * Decodes an AMQP initiation, delegating the decoding to a {@link ProtocolInitiation.Decoder}. + * + * @param session The Mina session. + * @param in The raw byte buffer. + * @param out The Mina object output gatherer to write decoded objects to. + * + * @return true if the data was decoded, false if more is needed and the data should accumulate. + * + * @throws Exception If the data cannot be decoded for any reason. + */ private boolean doDecodePI(IoSession session, ByteBuffer in, ProtocolDecoderOutput out) throws Exception { boolean enoughData = _piDecoder.decodable(session, in); @@ -88,10 +144,18 @@ public class AMQDecoder extends CumulativeProtocolDecoder else { _piDecoder.decode(session, in, out); + return true; } } + /** + * Sets the protocol initation flag, that determines whether decoding is handled by the data decoder of the protocol + * initation decoder. This method is expected to be called with false once protocol initation completes. + * + * @param expectProtocolInitiation true to use the protocol initiation decoder, false to use the + * data decoder. + */ public void setExpectProtocolInitiation(boolean expectProtocolInitiation) { _expectProtocolInitiation = expectProtocolInitiation; diff --git a/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java b/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java index fdb2e60c62..53f48ae1c8 100644 --- a/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java +++ b/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java @@ -7,9 +7,9 @@ * 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 @@ -23,19 +23,44 @@ package org.apache.qpid.codec; import org.apache.mina.common.IoSession; import org.apache.mina.filter.codec.ProtocolEncoder; import org.apache.mina.filter.codec.ProtocolEncoderOutput; + import org.apache.qpid.framing.AMQDataBlockEncoder; +/** + * AMQEncoder delegates encoding of AMQP to a data encoder. + * + *

+ *
CRC Card
Responsibilities Collaborations + *
Delegate AMQP encoding. {@link AMQDataBlockEncoder} + *
+ * + * @todo This class just delegates to another, so seems to be pointless. Unless it is going to handle some + * responsibilities in the future, then drop it. + */ public class AMQEncoder implements ProtocolEncoder { + /** The data encoder that is delegated to. */ private AMQDataBlockEncoder _dataBlockEncoder = new AMQDataBlockEncoder(); + /** + * Encodes AMQP. + * + * @param session The Mina session. + * @param message The data object to encode. + * @param out The Mina writer to output the raw byte data to. + * + * @throws Exception If the data cannot be encoded for any reason. + */ public void encode(IoSession session, Object message, ProtocolEncoderOutput out) throws Exception { _dataBlockEncoder.encode(session, message, out); } - public void dispose(IoSession session) throws Exception - { - - } + /** + * Does nothing. Called by Mina to allow this to clean up resources when it is no longer needed. + * + * @param session The Mina session. + */ + public void dispose(IoSession session) + { } } diff --git a/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java b/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java index fa75bd5fb3..375df2a45d 100644 --- a/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java +++ b/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java @@ -30,7 +30,7 @@ import org.apache.qpid.framing.AMQShortString; * constant also defines a short human readable description of the constant. * * @todo Why would a constant be defined that is not in the map? Seems more natural that getConstant should raise an - * exception for an unknown constant. Or else provide an explanation of why this is so. Also their is no way for + * exception for an unknown constant. Or else provide an explanation of why this is so. Also, there is no way for * callers to determine the unknown status of a code except by comparing its name to "unknown code", which would * seem to render this scheme a little bit pointless? * -- cgit v1.2.1