RE: [hyades-dev] Hyades Base Agent & Collector Interface Specification

["Naikawadi, Vishnu" <vishnu.naikawadi@xxxxxxxxx>]

Allan,

Thank you very much for a very detailed response.
I will update the document based upon your input.
For most of the points you mentioned, we also had similar
opinion during our internal reviews later but wanted to 
get some perspective from others too.

Few clarifications about the document, the scope of the document
is to specify the command protocol interface (basically the command-set).
And I would imagine writing another document "How to write an Agent"
in a detailed manner describing the steps involved in writing an agent though
it will be based on this document. And I think, I assumed few things while writing
the document and will add more information wherever required.

See my responses below for some of your comments.

Thanks
Vishnu

> -----Original Message-----
> From: hyades-dev-admin@xxxxxxxxxxx
> [mailto:hyades-dev-admin@xxxxxxxxxxx]On Behalf Of Allan K Pratt
> Sent: Monday, August 09, 2004 5:52 PM
> To: hyades-dev@xxxxxxxxxxx
> Subject: Re: [hyades-dev] Hyades Base Agent & Collector Interface
> Specification
> 
> 
> These are some review notes upon reading this document for 
> the first time.
> 
> As I read a document like this I try to wear several hats:
>         1. Does this cover everything I might need or want within its 
> scope?

This is what we should achieve by reviewing the document in our meeting.
I am sure there could be several commands we would like to add/remove.
And the goal here is to define only the base interface and leave out any special
cases and we can define/derive customized interfaces whenever such need arises.
But I agree that the base interface should be made broad enough to cover all
possible common cases of agent communication.

>         2. Could I implement an agent based only on this 
> document, without 
> ambiguity, contradiction, or holes?

As mentioned above, I feel that we should write another document
about how to write an agent as this document is just a specification.
But we definitely want to optimize this interface to cover all the possible
cases without any ambiguity.

>         3. Could I implement a CLIENT of an agent based only on this 
> document? Could I reliably drive a generic conforming agent?
> 
> I notice that some strings in this spec say they are UTF-8, 
> and others do 
> not. If you have a "Conventions" section at the top that says 
> ALL strings 
> are UTF-8, you won't have to worry about mentioning it in the 
> description 
> of every command and response that uses strings. If this 
> document is based 
> on some presumed conventions (at Layer 1 or Layer 0?) then you should 
> refer to those explicitly.
> 

Yes, I will add a  section for listing the presumed conventions.

> Oh, and are the UTF-8 strings also null-terminated? All 
> strings come with 
> a length count, but it can also be convenient (especially for 
> native C/C++ 
> code) if they're null terminated. This question applies 
> across the board, 
> at all levels of the protocol. And then make sure you say whether the 
> length count includes the null byte.
> 

Yes, all strings are null terminated and length count will include null byte also.

> 1.1.1.2.1 Initialize: Is there a requirement that somebody 
> call initialize 
> before doing anything else with the agent? If so, how can a program 
> driving the agent know whether Initialize has already been 
> called or not? 
> Consider a long-running agent which could survive across 
> multiple client 
> (Workbench) sessions. What if I call Initialize again, after 
> it's already 
> been called -- does the agent reset its state, or ignore the second 
> Initialize command, or what? I think we have to remember how 
> loose the 
> coupling is between agents and the code that drives them, and 
> not burden 
> the clients with preconditions ("Call Init before calling 
> anything else, 
> but only call it once").

The initial intention was to force a client or HCE to call Initialize but
after your and Luc's response, we reviewed again and it makes sense to
remove both Initialize and UnInitialize and leave it to agent to do it internally
during agent registration process and Terminate respectively.

> 1.1.1.2.2 Deregister: Once an agent is de-registered, it 
> seems like it 
> would be impossible to send it any more commands. How is this 
> different 
> from Terminate?

I will remove this command.

> 
> 1.1.1.2.3 Get Agent Name: the text says, "Agent Name is like a class 
> name." What does that mean? And why is there a reference to 
> agent metadata 
> in this section and nowhere else?
> 

I will update the definition here. About the reference to Metadata, there used be a command to
get metadata in the initial version and it was moved to agent manager interface.
I will change it.

> 1.1.1.2.5 Is Attached: does this query make sense for an 
> agent that can be 
> attached to multiple processes simultaneously? Is there a reason you 
> didn't write a query for me to find out WHAT process(es) the agent is 
> attached to?

I will add a separate "Attachable Interface" and add IsAttached, Attach and Detach
commands under this. Let us discuss tomorrow about the multiple process attachment
scenario and how we want to support it. 

> 1.1.1.2.7 Un-Initialize: What state is the agent in after calling 
> Un-Initialize? How is it different from Reset?

I will remove this command. The Reset is meant to reset the configuration.
And Un-Initialize for freeing any resource allocation done during Initialize.
But now that I am removing both Initialize and Uninitialize there will be less ambiguity.

> 1.1.1.3.4/5 Set/Add Property: I don't think it's necessary to 
> have "Add 
> Property" ... Is it so bad if "Set Property" has the behavior 
> of "Add" if 
> the property doesn't already exist?

Yes, I agree with you and will remove both Add and Remove Property commands.

> 1.1.1.3.7 Validate Configuration: The existence of this 
> command implies 
> that it's possible to send an invalid property set to the 
> agent without 
> the Set Property or Set Property Bag commands returning an 
> error. Is that 
> wise? What is the behavior of the agent if the configuration 
> is not valid?

Let us discuss tomorrow about the behavior when there is(are) invalid property(ies).

> 1.1.1.4.3 Get WSDL Definition: Why does this command's 
> description use 
> conditional language? The response data is "possibly" in WSDL format? 
> What's the alternative? This is a specification; it shouldn't 
> leave things 
> open-ended like this. If it's like this because the question is 
> unresolved, I'd like to see the description say so.

This is a requirement from choreography team. We were not sure what should
be the response - is it the whole document in WSDL format or just the agent configuration in XML.
I should have put a note there, sorry about that. I am planning to separate this command into 
"Web Services Interface" and add more commands later as we need them.


> 
> 1.1.1.4.4 Check Compatibility (with another agent): Besides 
> an affirmative 
> "yes" and an affirmative "no," another likely response is "I 
> don't know, 
> I've never heard of that agent." Or is that one of the error codes 
> available to the NOT_COMPATIBLE response? Since this document 
> doesn't list 
> error codes, I can't tell.
> 

Though my intention was just "Yes" or "No", I can see what you are saying.
May be we can add another response to indicate "NOT_COMPATIBLE" response.

> 1.1.1.5.1 Add Agent Event Listener: Is the mapping of Event 
> IDs to events 
> known? Or maybe events and their IDs are always 
> agent-defined. In that 
> case a generic client couldn't make use of this. Unless the 
> events and IDs 
> are defined in the WSDL or something else queryable. Also, 
> why do I have 
> to send the Server ID in this case? Isn't it implicitly "the 
> same server 
> that this command came through"?

The idea was to define all the Events as Interfaces (just like any other interface
we have defined so far). And agents can support/define specific event interfaces,
which means the interface IDs are pre-defined. Let us discuss tomorrow about
how to consume the events in a generic client. 

> 
> About add/remove agent event listener and also "set property 
> bag": are 
> these commands meant to be transactional? That is, if there 
> is an error in 
> processing ANY PART of the command, you reject and ignore ALL of it? 
> Otherwise I can see being *partly* deregistered, or having 
> changed *part* 
> of the property bag.
> 
> 1.1.1.6 Base Collector Interface: As noted in the text, this 
> interface is 
> designed for agents which collect observation data locally, 
> and return 
> that data to callers on demand. Not all agents work like 
> that; maybe there 
> should be two subclasses of base agents, for "live data" and 
> "aggregated 
> data" types.

Sure, we can sub-class them but we have to analyze and check
if there are major differences between these two types of agents
apart from data transfer mechanism.

> 1.1.1.6.1 Run: I can't make out this command. Is it required 
> to get data 
> collection going? I think it suffers from the same problems as Init.

We also had different opinions about the role of "Run" and "Start Monitoring".
Let us discuss tomorrow about this one.

> 1.1.1.6.8 Agent State Machine: This diagram doesn't match the 
> commands 
> listed above. The "Run" command doesn't appear in the 
> diagram, and the 
> "Configure" command does. "Get Data," too, is on the diagram 
> and not in 
> the description. Also, reading the diagram I notice that 
> Cancel is not 
> allowed from the Data Waiting state. If I've sent Stop and 
> then decide I 
> don't want the data, Cancel should be allowed. Also, Reset 
> seems like it 
> should be available from all states. Finally, I can't make 
> out the state 
> pattern or usage scenario for "Snapshot" and how it relates 
> to the "Data 
> Ready" event and state. 

The Agent State Machine diagram is not updated since the first version of
the document. Before discussing the validity of the diagram, I think we should
decide tomorrow if it makes sense to define a state transition diagram and forcing
an agent or collector (though the state diagram is prepared with main focus on collector)
to follow the state transition rules. There is a concern (from Hoang and Andy) 
if we can define a state diagram without any holes.

> 
> -- Allan Pratt, apratt@xxxxxxxxxx
> Rational software division of IBM
> 
> _______________________________________________
> hyades-dev mailing list
> hyades-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/hyades-dev
>