[CONF] Apache Qpid > Qpid Network Layer Update 2010

[confluence]

Qpid Network Layer Update 2010 Page edited by Andrew Kennedy Changes (2) ... | java-derby.0.8 | Java | 0-8 | 0-10 | Will negotiate AMQP version | h3. Network Layer Responsibilities The responsibilities for the network layer are split between four classes, which are described below, along with the interfaces (if any) they must implement. h4. {{NetworkTransport}}, {{IncomingNetworkTransport}} and {{OutgoingNetworkTransport}} This class represents the network transport mechanism and is used to make or receive connections using that mechanism. It will create {{NetworkConnection}} objects that represent an active connection using this mechanism. * _close_ - Close the transport and any associated {{NetworkConnection}} objects. * _getAddress_ Returns the address of the underlying socket that is either listening or was connected to. * _isCompatible_ Check whether the transport is compatible with a network protocol. * _connect_ Outgoing transport connection to a network address. * _accept_ Incoming transport listening for connections on a network address. h4. {{NetworkConnection}} This is a representation of a network connection, and is responsible for creating the {{Sender<ByteBuffer>}} implementation specific to the particular network transport. It may also be responsible for the creation of the receiver or network handler, or this may be left as the reposnsibility of the _connect_ method of the {{NetworkConnection}} in circumstances where both objects must be created at the same time. It is, however, always responsible for closing both the sender and receiver when it is closed. * _getSender_ Returns the {{Sender<ByteBuffer>}} object that sends bytes to the network interface for this connection * _close_ Clopses this connection and the associated receiver and sender objects, as well as any other network resources, and stops threads it may own * _getReadBytes_ Returns the number of bytes read over this connection * _getWrittenBytes_ Returns the number of bytes written to this connection * _getRemoteAddress_ Returns the remote address of the underlying socket. * _getLocalAddress_ Returns the local address of the underlying socket. h4. {{Sender<ByteBuffer>}} This class sends bytes to the network interface. h4. Network Handler This class receives bytes from the network interface and passes them on to a {{Receiver<ByteBuffer}} implementation that can handle and decode them. Also responsible for closing down the receiver when the underlying network interface is closed, or signalling an exception to the receiver when an error occurs. h2. Workflow ... Full Content Introduction This page covers analysis and design work for the work to refactor and improve the network layer code of the Qpid Java client and broker. The purpos this is to rationalise the network layer interfaces across all AMQP protocol versions, all network transport types and to allow the same network code to be used in both the client and the broker if required. Additionally, it allows for future changes to the network code in a manner that is independent of the protocols or transports. Further improvements to the broker have also be included in the scope of this work, including making the ApplicationRegistry object a singleton, and collecting broker startup code in a single class to allow various use cases, such as OSGi modularisation or system testing to be simplified. On the client side, 0-10 VM protocol support is added, as well as better failover and exception handling in the 0-10 code paths. In general, the coupling between different parts of the system is reduced and the responsibilities of individual classes are reduced and better defined. Test coverage is also improved across all supported AMQP protocols, and many test cases that are currently failing under 0-10 are fixed. A Presentation is available describing the status as of September 2010, when the bulk of this work was initiated and carried out. More recently, in February 2011 the code has been revisited and merged with the trunk in preparation for being committed as part of the 0.11 development stream and with the intention of the inclusion in the 0.12 release.. Original Transport Code 0-8 and 0-9 Client AMQConnectionDelegate_8_0#makeBrokerConnection(BrokerDetails) TransportConnection#getInstance(BrokerDetails) ITransportConnection#connect(AMQProtocolhandler, BrokerDetails) MinaNetworkDriver#open(...) 0-10 Client AMQConnectionDelegate_0_10#makeBrokerConnection(BrokerDetails) Connection#connect(ConnectionSettings) TransportBuilder#init(Connection) Transport#getTransport() Transport#init(ConnectionSettings) TransportBuilder#buildSenderPipe() TransportBuilder#buildReceiverPipe() Broker Main#startup() MinaNetworkDriver#bind(...) Design New set of interfaces to define a 0-10 (and maybe 1-0 too) transport interface. Note that this means MINA, Grizzly, NII etc. rather than TCP/IP, UDP, Unix Sockets, Pipes or whatever. It should be possible to have different underlying transport mechanism, however, so when MINA is specified, we can further implement the Socket, VmPipe etc. connectors. This diagram shows the relationship between various components in the networking layer of the Qpid broker and client. Classes and Interfaces This diagram shows the original Java classes involved in the Qpid networking layer. The intention of the work is to simplify the interface hierarchy, and in particular get rid of situations such as the ProtocolEngine_0_10 interface, where A implements B which extends C, and also A extends B' which implements C, this being rather redundant. Additional issues with interfaces include duplicate method declarations, where a method is defined in interface A, B extends A but still declares the same method. These should be removed where possible. Ideally, ProtocolEngine will be replaced by Receiver<ByteBuffer> everywhere, and the extra methods moved to a transport layer interface. I came across the following snippet in AMQConnectionDelegate_8_0#makeBrokerConnection() and wondered what the UseTransportIo property was for: // TODO: use system property thingy for this if (System.getProperty("UseTransportIo", "false").equals("false")) { TransportConnection.getInstance(brokerDetail).connect(_conn._protocolHandler, brokerDetail); } else { _conn.getProtocolHandler().createIoTransportSession(brokerDetail); } See viewvc for when the change was made. As far as I can tell, the code that would be called if this property is set (for instance IoTransport.connect_0_9() and some associated classes that seem to be 0-9 specific) is not tested, or used, and I have difficulty understanding the purpose. It looks very much to me like an attempt at another transport layer, but only implemented for the 0-9 protocol? Interestingly, it uses a Binding<X,Y> object, which also crops up in the Toy* classes and their associated MinaHandler. These are the classes that were either deleted or renamed. The reason for my interest in this is that I am looking at harmonising the transport mechanisms and introducing a mechanism to allow different transport layers (MINA, Java NIO, Netty, and so forth) to be used independently of the protocol (0-8, 0-10, maybe even 1-0 eventually!) or underlying transport mechanism (TCP, UDP, VM) and I keep discovering classes that appear to do the same thing, but subtly different, or are just not used. I will probably be able to use some of the logic from these classes but I see no benefit from introducing a 0-9 only (apparently) transport layer that is completely untested. Additionally, I have been looking at the ProtocolEngine interface, and I discovered that the getWrittenBytes()/getReadBytes() pair of methods that are present there are not exposed through the MBean (although they are there, just commented out) and where they are used, they are used incorrectly (both getWrittenBytes() and getReadBytes() methods delegated to getWrittenBytes(). This diagram shows the changes made to the Java classes involved in the Qpid networking layer. Broker Startup The broker startup mechanism should be modified to allow use of a common network transport layer, and be configurable either from the command-line or through system properties set at a client when using the in-vm mechanism. The following classes would probably be required: BrokerInstance This represents a broker instance that can be started and shut down (methods from Main originally) where the startup method should take a BrokerOptions configuration object. The instance would be created and methods called from Main, the BrokerActivator or from a client wanting an in-vm broker. This class should also contain instance fields that represent either the broker is embedded and contain a copy of the OSGi context it is running in. BrokerOptions The set of command-line options that are parsed out in the existing Main (ports and protocol version exclusions and similar) should be stored in a separate object, that can then be created independently for situations where broker startup does not happen on the command-line. Main Move startup() and shutdown() methods to the BrokerInstance class, and build a BrokerOptions configuration from the command-line options here. If this class has to shut down the broker it started, it can safely call System.exit if needed, as well, after telling the instance to shut down. BrokerActivator An OSGi activator that parses the configuration from a property file or similar to obtain a BrokerOptions and uses that to call startup on a BrokerInstance. Similarly, when the BrokerActivator shuts down, it should shut the BrokerInstance down cleanly. This is distinct from the activator used by Felix when starting up our embedded container, and this is where you can set the flag that would indicate that the broker is embedded, so that the PluginManager knows not to start a Felix OSGi container, but to use the existing OSGi context instead. VmBroker A class used by a client vm:// connection, that starts a BrokerInstance instance in the same JVM. The BrokerOptions would be created using system properties, or arguments passed using the broker connection URL. QpidBrokerTestCase The JUnit test case that is used for system tests that start a broker. This will now create a BrokerInstance and start it using a set of BrokerOption}}s created from the test profile properties and other system properties, as appropriate in the {{setUp() method, and shutting down the instance in the tearDown() method. Test Profiles Test profiles are created by adding a file named profile.testprofile to the qpid/java/test-profiles directory. This file is parsed as a series of properties, adding to and overriding any set in the default.testprofile file. The default test profile has now been deprecated, in favour of using this file as simply a repository for the default values for test properties. Profile Broker Type Broker AMQP Client AMQP Notes vm.0.10 VM 0-10 0-10 Default profile vm.0.9.1 VM 0-9-1 0-9-1   vm.0.9 VM 0-9 0-9   vm.0.8 VM 0-8 0-8   java.0.10 Java 0-10 0-10   java.0.9.1 Java 0-9-1 0-10 Will negotiate AMQP version java.0.9 Java 0-9 0-10 Will negotiate AMQP version java.0.8 Java 0-8 0-10 Will negotiate AMQP version java-derby.0.10 Java 0-10 0-10   java-derby.0.9.1 Java 0-9-1 0-10 Will negotiate AMQP version java-derby.0.9 Java 0-9 0-10 Will negotiate AMQP version java-derby.0.8 Java 0-8 0-10 Will negotiate AMQP version Network Layer Responsibilities The responsibilities for the network layer are split between four classes, which are described below, along with the interfaces (if any) they must implement. NetworkTransport, IncomingNetworkTransport and OutgoingNetworkTransport This class represents the network transport mechanism and is used to make or receive connections using that mechanism. It will create NetworkConnection objects that represent an active connection using this mechanism. close - Close the transport and any associated NetworkConnection objects. getAddress Returns the address of the underlying socket that is either listening or was connected to. isCompatible Check whether the transport is compatible with a network protocol. connect Outgoing transport connection to a network address. accept Incoming transport listening for connections on a network address. NetworkConnection This is a representation of a network connection, and is responsible for creating the Sender<ByteBuffer> implementation specific to the particular network transport. It may also be responsible for the creation of the receiver or network handler, or this may be left as the reposnsibility of the connect method of the NetworkConnection in circumstances where both objects must be created at the same time. It is, however, always responsible for closing both the sender and receiver when it is closed. getSender Returns the Sender<ByteBuffer> object that sends bytes to the network interface for this connection close Clopses this connection and the associated receiver and sender objects, as well as any other network resources, and stops threads it may own getReadBytes Returns the number of bytes read over this connection getWrittenBytes Returns the number of bytes written to this connection getRemoteAddress Returns the remote address of the underlying socket. getLocalAddress Returns the local address of the underlying socket. Sender<ByteBuffer> This class sends bytes to the network interface. Network Handler This class receives bytes from the network interface and passes them on to a Receiver<ByteBuffer implementation that can handle and decode them. Also responsible for closing down the receiver when the underlying network interface is closed, or signalling an exception to the receiver when an error occurs. Workflow Rationalise 0-10 Transport Interface QPID-2811 0.11 In Progress Create or modify current transport mechanism classes and interfaces to make them more generic and allow for other mechanisms and protocols to be added in a modular way. Update 0-10 connection configuration mechanism and properties QPID-2812 0.11 In Progress Update the 0-10 connection settings and system properties to rationalise the configuration of the connection mechanism/transport/protocol. This may depend on how different transport mechanisms are loaded, e.g. if we use OSGi plugins or not. It would be nice to make things consistent across all protocols, so that broker addressing does not change. Note that some transports may not support all types of broker addressing,and this has to fail gracefully. This will also include removal of some classes and options, such as the IoTransport configuration property. This property is present as an apparently untested 0-9 protocol only option, and uses an entirely new mechanism to connect the transport layer to the MINA mechanism. Since the intent of the preceding JIRA is to harmonise the transport layer interfaces between protocols, I believe this is an unnecessary complication. Update current 0-10 socket connection to conform to new mechanism QPID-2813 0.11 In Progress Make any additional changes to the existing transport to allow it to conform fully to the changes made in QPID-2811 and QPID-2812 Create TCP based 0-10 MINA transport QPID-2816 0.11 In Progress Create a 0-10 MINA transport that implements the tcp:// protocol for broker communication Create MINA InVM 0-10 Transport QPID-2814 0.11 In Progress Create a MINA transport that implements the vm:// VmPipe protocol, to allow for in-vm communication with the 0-10 protocol Make InVM broker startup protocol independent QPID-2815 0.11 In Progress Update the way the in-vm broker is started to decouple it from any particular protocol version Make Transport mechanisms into OSGi plugins QPID-2818 TODO Make the transport mechanism pluggable using OSGi on both the broker and the client Add additional pluggable transport mechanisms QPID-2819 TODO Add additional transport mechanisms such as Netty or Grizzly Make ApplicationRegistry a Singleton QPID-3026 0.11 In Progress There can only be a singlr instance of the ApplicationRegistry in a particular JVM Change Notification Preferences View Online | View Changes | Add Comment --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:commits-subscr...@qpid.apache.org