Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm working on a large project at the moment and I'm trying to document the communication protocol that sits on top of a message queue middleware.

The documentation is intended for another organisation that is going to be implementing a new back end to the client.

The messages format uses protocol buffers, so I'm less interested in describing the wire format.

I'm interested in documenting the interactions between the service and client. A typical interaction might be something like:

  1. Client subscribes to Channel1
  2. Client pushes RequestForStream to Queue1
  3. Service reads from Queue1 publishes StreamResponse (containing endpoint to subscribe to, Channel2) to Channel1 and if successful starts publishing notifications to Channel2
  4. Client receives from Channel1 and subscribes to Channel2
  5. More stuff...

How can I best document scenarios like this? Does anyone know of any examples of documented interactions with Queues and channels?

Edit: I am not writing a Message Queue. I am using a JMS-like middleware named Nirvana. I want to document the application built on top of the Message Queue system.

Edit 2: In UML how would I model a Queue or Channel? Would I show them on a sequence diagram?

share|improve this question
2  
Are UML communication or sequence diagrams an option for you? –  Frank Feb 28 '13 at 12:10
    
@Frank yes, but I didnt want to presume any possible solutions in my Q, if I'd said in UML, all the answers would be UML. –  Dave Hillier Feb 28 '13 at 13:25
    
Is your protocol similar to an existing public protocol? If so, did you look for how that protocol is documented? Also, it most certainly will be overkill, but making use of some government standards documents may help, because they are designed for the exact purpose you described. In particular, you are looking for an example Interface Design Description (IDD). A template for an IDD is defined in DI-IPSC-81436. But that might not help much if you can't find a corresponding example. –  Dunk Feb 28 '13 at 14:46

2 Answers 2

I am the author of pg_message_queue which is a very light-weight channel/queue system in PostgreSQL designed to facilitate database-level integration. Messages can then be forwarded to a heavier message queue, or the like, or they can just be processed. The use case is for things like "I want to send an email from the database" and helps solve the problem for PostgreSQL without really awkward transactional processing problems that could result.

Our documentation is at http://pgxn.org/dist/pg_message_queue/

I won't say it is the best documentation out there but it is sufficient for our use case. Compare to http://www.rabbitmq.com/documentation.html which is the rabbitmq documentation and you will see how different the requirements of the documentation in fact are.

But like all docs, keep your audience and use case in mind, and go through it conceptually and programmatically.

Edit Ok I see what I misunderstood. I would suggest starting at least with an outline of technical documentation. If you have it from someone else, great. If not, at least come up with an outline of what a technical programmer's manual should cover.

It sounds to me like you are looking at documenting a network protocol rather than an API. Sorry, I did read it and I missed that part. It's still not clear to me if this is direct over TCP, or over HTTP, or something else. To the extent you are reusing other protocols, the work is easier.

Either way, I would divide up the documentation into three sections. The first would cover message structure generally. This would include headers, message body specifications, etc. but would be at a general enough level to provide a reference for section 2.

Section 2 would cover the specifics for each message type. Again it depends on what exactly you are re-using how much depth you need to go into.

Section 3 would provide examples for how the communication would work using sets of mocked up messages.

share|improve this answer
    
I am not writing a Message Queue. I am using a JMS-like middleware named Nirvana. I want to document the application built on top of the Message Queue system. The audience is the programmer who write the services. –  Dave Hillier Feb 28 '13 at 11:17
    
I think you've misread the question - or perhaps just read the headline and not the body. –  Dave Hillier Feb 28 '13 at 11:30
    
I read it. My point is that the question as written is very vague. My qualifications are that I have written and documented a message queue. The key thing is to keep your audience in mind and pay attention to conceptual structure. What is appropriate for one audience and one use case may not be for another. In one case, perhaps sample code should be included. In another you want to provide detailed API specifications. The problem is there isn't a single answer here and it depends. –  Chris Travers Feb 28 '13 at 11:57
    
You are well qualified to answer the question, but you have not understood it, your thinking is stuck the level lower, as that's what your experience is. I'll ask another Q for you, how would someone document the protocol that they have built on top of your framework? –  Dave Hillier Feb 28 '13 at 12:05
    
I have provided an example of the kind of thing that I need to document. Can you think of a better way than the numbered list? –  Dave Hillier Feb 28 '13 at 12:08

I have used pi-calculus to document and analysis high level processes. There isn't a standard language for pi-calculus, but for a tool I wrote I used a simple one-line per atomic step language, which would look something like:

process Client
    # initialise client process with the channel to subscribe to 
    recv self Init ( channel1 : channel, queue1 : channel ) 
    # send request to server
    send queue1 RequestForStream ( channel1 )
    # bind channel in response to channel2
    recv channel1 StreamResponse ( channel2 : channel )

    loop:
    choice
        # either receive a notification or stop
        recv channel2 Notification ()
            goto loop
        recv channel2 Stop()
            stop

process Server
    new channel2
    # wait for request
    recv self RequestForStream ( client : channel )
    # send response to client with channel2 to send
    send client StreamResponse ( channel2 ) 
    # send notifications on channel2
    send channel2 Notification ()
    send channel2 Notification ()
    send channel2 Stop ()
    stop


# test
process Test
    c := start Client
    s := start Server

    send c Init ( c, s )
    stop


start Test

the extra stop parts are there as the tool is to detect deadlocks livelocks and races.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.