[CONF] Apache Qpid > AMQP 1.0 JMS Client Requirements and Design

[Phil Harvey (Confluence)]

AMQP 1.0 JMS Client Requirements and Design Page edited by Phil Harvey Changes (32) ... h4. Testing strategy * Goals: ** * Running all the tests should be fast (it should be exceptional for a test to take more than five seconds). ** Tests operate at the correct level. Specifically: * Tests operate at the correct level for their test type (see next section). Specifically: *** Simple logic bugs cause unit tests to fail. *** Errors in collaboration logic cause integration module tests to fail. ** Most (if not all) of our integration tests should run in-process. ** The official JMS 2 TCK tests will also be run against the client. * The following third-part tests will also be run against the client: ** Official JMS 2 TCK. ** Joram. h5. Integration tests h5. Test types We will write a number of each of the following tests. * Unit test: class that attempts to test an individual class. Some unit tests will incidentally tests several other closely related classes too. * Module test: a class that attempts to test the full JMS client, but using a stub/mock etc instead of a broker. In most cases, we want to test that: ** Calling specific JMS methods causes the correct AMQP to be sent, and ** The client correctly handles AMQP sent by its peer. * System test: a class that tests the behaviour of the JMS client when communicating with a real peer such as the Qpid Broker. Assertions will be written mostly in terms of the JMS API. We may re-use some of the existing Qpid system tests. For each test, our main choice is which layer to designate as the boundary for our tests. Everything "below" this boundary will be replaced with a mock implementation ("mock" is defined in a broad sense - it does not assume a imply the use of a mocking framework). h5. Module tests Our options are listed below in increasing system boundary extent. As the extent increases, the usual trade-offs apply: * More layers of the real JMS client will be exercised, thereby increasing the confidence that our tests give us. * We get less control over the tests, both in terms of their inputs and the assertions we can test. * Tests become harder to debug. The following diagram shows how module tests will work: || Layer to mock || Comments || | *Proton* | *Simple,* in that our mock layer can be implemented in terms of Proton model objects without worrying about streams of bytes. This should also make it easier to debug tests.\\ {noformat} *Will not catch Proton bugs*. \\ +================================+ *Hard to ensure that our mock Proton behaves consistently* with respect to the real thing.\\ | | *Proton encoder and decoder*. \\ For simplicity, the mock encoder and decoder would produce and consume FrameBody objects respectively, rather than bytes.\\ On a test-by-test basis, the mock encoder could be configured to apply assertions to allow us to check that a particular JMS operation caused the right frame(s) to be generated. Similarly, the mock decoder could generate _FrameBody{_}s to simulate the Broker's behaviour.  This would allow us to replace Proton's Transport layer with a no-op implementation.\\ | JUnit test Alternatively, the the assertions and mock behaviour (for output and input respectively) could be applied to the Transport rather than the encoder/decoder.\\ | Gives us *full control*, i.e. we can check exactly which frames were produced.  Can also control which frames are sent to the client to a greater extent than if a Proton peer was generating them.  This doesn't just apply to simulating error scenarios - some valid sequences of happy-path frames are impossible to generate using Proton.\\ | 1. Create an in-process TestAmqpPeer | 2. Set up TestAmqpPeer behaviour and expectations | 3. Call some JMS methods However, writing tests in terms of frames is *less intuitive* than expressing them in terms of Proton model objects.  The former is a sequence of state transitions whereas the latter represents the actual state of the system.\\ | | | | +================================+ | *The broker (in-process)*. \\ We would modify Driver to produce output in-process rather than requiring a Socket. \\ The bytes would be exchanged with a mock Broker which would be a thin wrapper round Proton.  The mock Broker would use test-specific logic to: \\ \- Assert the expected state of its local Proton model objects \\ \- Simulate a real Broker's output \\ Tests using this option would be run against both proton-j and proton-jni. \\ \\ | This option should still run acceptably fast despite containing almost all the layers of the real JMS client.\\ | | | | | | Cannot simulate all scenarios we want to test, e.g. server redirect, or certain error cases. \\ | | *The broker (out-of-process)*. \\ We would either write a simple broker or use the existing one. \\ The client test would more closely resemble a conventional application than a JUnit test. | Useful for testing multi-threaded behaviour | | | \|/ | | +================================+ | | | | | | JMS client | | | | | +================================+ | | | | | | | | | | \|/ | | | +======================+ | | | | Proton | | | | | | | | | | Message | Engine | | | | | | | | | | +=========+============+ | | | /|\ | | | | | | \|/ \|/ \|/ | +======================================= | | | | In-process Driver | | | +======================================= | /|\ | | | | Bytes | | \|/ \|/ +===================================+ | | TestAmqpPeer | +===================================+ {noformat} h6. In-process Driver implementation * Should use a threading model that is as similar as possible to the TCP/IP driver, to make the test as realistic as possible. * Should expose methods to give the test a way to control, for a given connection, the relative order of (1) events in the "application" thread (typically the main test thread) and (2) events in the driver thread. This should reduce the number of race condition bugs in our code. We will probably implement this control using techniques such as: ** [Latches|http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/CountDownLatch.html], [CyclicBarrier|http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/CyclicBarrier.html]s etc. ** Controlling the chunking of the byte production/consumption by both the In-process Driver and the TestAmqpPeer. We expect all of the above mocking options to be used at some point. *Initially we will favour mocking the broker in-process where possible*. This is because: # It is easy to set up, with minimal changes to Proton. # This is very nearly an end-to-end test, which will give us useful reasssurance particularly in the early stages of the project. h6. TestAmqpPeer implementation *Each test will give behaviour to a TestAmqpPeer*. This behaviour will mostly be expressed in terms of AMQP frames. Here are prose examples (we don't yet know how these will be expressed in code) ||Expected frame||Frame to respond with|| |An Open frame with container-id "xyz"|The following canned Open frame: ...| ||Expected frame||Frame to respond with|| |An Open frame with container-id "xyz"|The following sequence of frames representing a refused connection| ||Expected frame||Frame to respond with|| |Any Open|Canned Open frame: ...| |Any Begin|Canned Begin frame: ...| |An Attach matching the following criteria: ...|The following Attach: ...| In order to increase our confidence in the AMQP interoperabilty of the JMS client, we want to avoid using the same Proton stack in the test peer as in the client. Therefore, *Decoding and encoding will be done using proton-api's Data class.* The AmqpTestPeer will minimise its use of other Proton classes. h6. SASL Most tests will perform minimal SASL negotiation, simulating simple, successful SASL authentication. We will write specific SASL tests to exercise more complex scenarios. Full Content This page describes the requirements and initial design of the new Qpid JMS Client that supports AMQP 1.0 (simply referred to as the "Qpid JMS Client" below). Requirements Functional requirements Phase 0 Phase 1 Phase 2 Non-functional requirements Out of scope Design Layers Public API Locking I/O layer Logging Testing strategy Test types Module tests In-process Driver implementation TestAmqpPeer implementation SASL Requirements Functional requirements AMQP 1.0 JMS 2 JMS 1.1 support will be added in the future if demand requires. ONGOING: Contribute to the JMS mapping work within the OASIS AMQP Binding & Mappings TC The following sub-sections allocate the functional requirements to several sequential project phases. Phase 0 This is the initial set-up of the basics. Open and close a connection. Includes writing automated tests. This will implicitly require work on: Project folder structure Build tool configuration CI server job Automated HTML documentation generation. Phase 1 Synchronous, Auto-Ack style 'simple client' Main operations on JMS Connections, Sessions, Consumers, Producers, Queues, Message (Text?). Include closing/stopping/deleting where applicable. Configuration Ability to configure settings such as pre-fetch etc TODO per connection or per consumer or both? If the latter then not sure how to pass this setting in (address options?), given that JMS API doesn't offer an obvious way to do it. TODO define how JNDI configuration will work SASL Correct handling of non-happy path scenarios, namely: Unexpected errors Failures that are nevertheless AMQP-compliant, e.g. the Broker spontaneously sends a Close or End frame. Timeouts due to connectivity failure etc. Necessary because of the asynchronous nature of AMQP. Interruption of application-owned threads. Phase 2 SSL Transactions Client Ack Selectors JNDI MessageListener.onMessage() Durable Subscriptions JMS 2.0 features: Asynchronous send Shared Topic Subscriptions Non-functional requirements Logging Should play nicely with application logging, e.g. allow the application to plug in its choice of third party logging framework, which would also be passed through to Proton if possible. See PROTON-343 - "Add a pluggable Proton logging layer". Should allow control of logging thresholds for categories including: A specific object, e.g. a Connection A logical function, e.g. network I/O Initially will only run on Java 1.7 (because some JMS 2 features require Java 1.7). Out of scope AMQP 0-x ADDR and BURL addressing formats Failover. Instead, this will be implemented in the future either entirely below or entirely above the client code. Accepting legacy system properties (unelss they happen to match what we would choose now). Design Layers +================================+ | | JMS | | Implementations of javax.jms | +================================+ | | \|/ +================================+ | | AMQP | | Wrappers around Proton's engine | classes, primarily to add locking | +================================+ | | | | \|/ | +======================+ | | Proton | | | | | | Message | Engine | | | | | | +=========+============+ | /|\ | | | | \|/ +==================== | | JMS Driver interface | +===================== /|\ | +--------------+ | | | | | | +===========+ +============== | | | Socket | | driver | Another driver, | (might use | e.g. in-VM | Proton's Driver) | | | +===========+ +============== | | TCP/IP | \|/ +================================+ | | Broker | +================================+ Public API Goals: Minimal public API Possible to write JMS applications that have a compile-time dependency on the javax.jms interfaces and not on Qpid-specific classes. Minor releases maintain backwards compatibility between minor releases. The public API consists of: The JMS interfaces (probably provided by a third party library such as Geronomio Spec). The constructor(s) for Qpid's implementation of javax.jms.ConnectionFactory and its sub-interfaces. Qpid's javax.naming.spi.InitialContextFactory implementation. Note that the logging output and logging category names also constitute a public interface. In the future, the public API may need to be extended or more precisely specified (e.g. to include details of the mapping between JMS and AMQP when using MapMessage and ObjectMessage etc). Locking Goals: Minimise the number of locks Define the correct locking order Threads fall into two categories: Application threads using the JMS API. Only use the top half of the Proton API. One or more driver threads for I/O. Managed by the JMS client. Only use the bottom half of the Proton API. For a given connection: State shared by multiple application threads (namely the state of the objects in the JMS layer) is guarded by the JMS ConnectionLock. State shared by the application and driver threads is guarded by the AmqpConnection lock. This shared state is: A small number of flags the application and driver threads use to indicate to each other that "something has changed". The Proton objects. This sharing occurs inside Proton but needs to be guarded by the JMS client because Proton itself is not thread-safe. Synchronous operations must follow the locking scheme indicated by the following pseudo-code: jmsObject.doStuff obtain ConnectionLock amqpObject.doAmqpStuff obtain amqpConnection lock protonObject.doProtonStuff release amqpConnection lock JmsConnection.stateChanged (event notification, e.g. to wake up the driver so that I/O occurs) release ConnectionLock Where operations need to wait for a "remote" operation to complete, they must follow the scheme indicated by the following pseudo-code: jmsObject.doRemoteStuff obtain ConnectionLock ... JmsConnection.waitUntil(predicateObject) obtain amqConnection lock amqConnection.wait() (the Driver thread calls amqConnection.notifyAll()) ... evaluate predicate ... release amqConnection lock release ConnectionLock This ensures that when the predicate object is invoked the thread will already possess both the JmsConnection lock and the AmqpConnection lock. I/O layer Goals: Encapsulate any 3rd party library as much as possible Allow transport to be easily swapped out to allow, for example: in-VM operation WebSockets SCTP Accepting Connection. Useful if the client is behind a firewall that forbids outbound connections. TODO - design I/O Use Netty? Logging Goals: Consistent use of logging levels TODO more... TODO Testing strategy Goals: Running all the tests should be fast (it should be exceptional for a test to take more than five seconds). Tests operate at the correct level for their test type (see next section). Specifically: Simple logic bugs cause unit tests to fail. Errors in collaboration logic cause module tests to fail. The following third-part tests will also be run against the client: Official JMS 2 TCK. Joram. Test types We will write a number of each of the following tests. Unit test: class that attempts to test an individual class. Some unit tests will incidentally tests several other closely related classes too. Module test: a class that attempts to test the full JMS client, but using a stub/mock etc instead of a broker. In most cases, we want to test that: Calling specific JMS methods causes the correct AMQP to be sent, and The client correctly handles AMQP sent by its peer. System test: a class that tests the behaviour of the JMS client when communicating with a real peer such as the Qpid Broker. Assertions will be written mostly in terms of the JMS API. We may re-use some of the existing Qpid system tests. Module tests The following diagram shows how module tests will work: +================================+ | | JUnit test | | 1. Create an in-process TestAmqpPeer | 2. Set up TestAmqpPeer behaviour and expectations | 3. Call some JMS methods | +================================+ | | | | | | | | \|/ | | +================================+ | | | | | | JMS client | | | | | +================================+ | | | | | | | | | | \|/ | | | +======================+ | | | | Proton | | | | | | | | | | Message | Engine | | | | | | | | | | +=========+============+ | | | /|\ | | | | | | \|/ \|/ \|/ | +======================================= | | | | In-process Driver | | | +======================================= | /|\ | | | | Bytes | | \|/ \|/ +===================================+ | | TestAmqpPeer | +===================================+ In-process Driver implementation Should use a threading model that is as similar as possible to the TCP/IP driver, to make the test as realistic as possible. Should expose methods to give the test a way to control, for a given connection, the relative order of (1) events in the "application" thread (typically the main test thread) and (2) events in the driver thread. This should reduce the number of race condition bugs in our code. We will probably implement this control using techniques such as: Latches, CyclicBarriers etc. Controlling the chunking of the byte production/consumption by both the In-process Driver and the TestAmqpPeer. TestAmqpPeer implementation Each test will give behaviour to a TestAmqpPeer. This behaviour will mostly be expressed in terms of AMQP frames. Here are prose examples (we don't yet know how these will be expressed in code) Expected frame Frame to respond with An Open frame with container-id "xyz" The following canned Open frame: ... Expected frame Frame to respond with An Open frame with container-id "xyz" The following sequence of frames representing a refused connection Expected frame Frame to respond with Any Open Canned Open frame: ... Any Begin Canned Begin frame: ... An Attach matching the following criteria: ... The following Attach: ... In order to increase our confidence in the AMQP interoperabilty of the JMS client, we want to avoid using the same Proton stack in the test peer as in the client. Therefore, Decoding and encoding will be done using proton-api's Data class. The AmqpTestPeer will minimise its use of other Proton classes. SASL Most tests will perform minimal SASL negotiation, simulating simple, successful SASL authentication. We will write specific SASL tests to exercise more complex scenarios. Stop watching space | Change email notification preferences View Online | View Changes | Add Comment --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org