eCAP

Adapted content notification and consumption

Asked by Philip Allison

I'm slightly confused as to exactly what behaviour a good eCAP host should have in order to reliably retrieve all the adapted body from an adapter. As per the answer to my previous question, the noteAbContentDone() call is supposed to be purely informational: a hint that the adapter has stopped producing new adapted body, it does not necessarily mean that the host has retrieved all of the currently available data.

Should adapters continue calling noteAbContentAvailable() until the host has retrieved all data, or is it the host's job to continue calling abContent() and abContentShift() until they receive no data?

Additionally, prior to the adapter calling noteAbContentDone(), should the host only call abContent()/abContentShift() in response to noteAbContentAvailable(), or should it continue calling them as often as necessary until no more data is available, then what for the next call to noteAbContentAvailable()? What is the correct way for an adapter to signify that there is currently no data in response to abContent()?

Question information

Language:
English Edit question
Status:
Solved
For:
eCAP Edit question
Assignee:
No assignee Edit question
Solved by:
Alex Rousskov
Solved:
Last query:
Last reply:
Revision history for this message
Philip Allison (mangobrain) said : 		#1

Oops - "then what for the next call to noteAbContentAvailable()" should be "then *wait* for the next call".

Revision history for this message
Best Alex Rousskov (rousskov) said : 		#2

All note* calls are pretty much "informational". The overall model for body management is a shared body buffer, a set of notifications that the producing agent uses to inform the consumer about the changes in the state of that shared buffer, and a set of calls that the consuming agent uses to influence the production.

* When should an adapter call Host::Xaction::noteAbContentAvailable?

The adapter should call noteAbContentAvailable when the adapter has produced new adapted body content. Performance aside, it does not hurt to call this method more often than necessary.

* When should a host call Adapter::Xaction::abContent and abContentShift?

The host may call these methods at any time between the calls to Adapter::Xaction::abMake and abStopMaking. There is no limit on the number of times abContent and abContentShift methods may be called.

* What should Adapter::Xaction::abContent return if there is no adapted content available at the time of the call?

The adapter should return an empty Area (i.e., an area with zero size). For example, an Area() object can be returned.

Revision history for this message
Philip Allison (mangobrain) said : 		#3

Thanks Alex Rousskov, that solved my question.

Revision history for this message
Philip Allison (mangobrain) said : 		#4

Thanks, that confirms what I now understand about the API. I'm still not sure if it's the right fit for the project I'm researching, but that is primarily for other reasons - the eCAP API itself seems sound, now that I've got my head round it. I apologise if the tone of yesterday's question was a bit abrupt, it was supposed to be more like "I'm not sure I understand", but it probably came across as "this is all wrong". Thankyou for responding quickly, and I hope the bug reports have been helpful.