[news.eclipse.technology.ecf] ECF documentation comments

[Li-Te <li-te_cheng@xxxxxxxxxx>]

Hi,

Congrats on getting accepted as a project!  Looking forward to seeing 
this happen.

Minor point : on the ECF "dev resources" page, 
http://www.eclipse.org/ecf/resources.html , it still says the newsgroup 
is eclipse.technology.ecomm ... should be changed to ecf instead.

I was reading through the ECF documentation page at 
http://www.eclipse.org/ecf/documentation.html and have a number of 
questions/comments.   I'm guessing most of this is due to synching up 
the docs with recent API changes:

Under "ISharedObject Lifecycle / Initialization"...

"After it has been constructed the container to which it was added will 
invoke the ***ISharedObject.init*** ... ISharedObjects created outside 
of a container, will have their ***ISharedObjectConfig.init*** method 
invoked immediately as part of being added to the container."

Q: Shouldn't the "ISharedObjectConfig.init()" actually be 
ISharedObject.init()?

"The ISharedObjectConfig parameter provides the ISharedObject with 
access...via a call to ISharedObjectConfig.getContext().  The 
ISharedObject is not considered initialized until after the init method 
is completed, and therefore the ISharedObjectContext is not available 
until after the init method returns."

Q: Should there be a ISharedObject.getConfig() method, so the config and 
the context objects can be accessed outside the init() method?  This 
especially important when sending messages, because ISharedObjectContext 
is required, and it's only available from ISharedObjectConfig.

Q: Because there is an implied notion of initialized or not-initialized 
states, should there be a ISharedObject.isInitialized() method?

Q: Would it be better to keep things consistent with init() and 
isInitialized by having a SharedObjectInitializedEvent (instead of 
SharedObjectActivatedEvent)?


Under "Relationship to its container"...

"ISharedObjects can be created outside a ISharedObjectContainer and then 
 later added to it using the ISharedObjectContainer.addSharedObject() 
method"

Q: I see addSharedObject under ISharedObjectManager, not 
ISharedObjectContainer - is this a typo?


Under "Sending Messages" and "Receiving Events"

Q: I see "asynchronous" used througout the descriptions, but no mention 
of "synchronous".  Is "asynchronous" == "non-blocking call" , or 
"asynchronous" == "send like email"?

Q: the ISharedObjectContext.sendMessage method would trigger handleEvent 
on the receiving ISharedObject.  Is it assumed that all messaging events 
must subclass the SharedObjectEvent interface?  Or should there be a 
base SharedObjectMessageEvent interface that messaging events should 
subclass, with content corresponding to the parameters in sendMessage(), 
i.e.

public interface ISharedObjectMessageEvent extends SharedObjectEvent
{
     public ID getToContainerID();
     public Object getData();
}

If you are concerned about passing data objects around (you might want 
to suggest Serializable instead, but that ties down implementations a 
lot), then drop the notion of a ISharedObjectMessageEvent, and push 
getToContainerID() up to tSharedObjectEvent.  It might be useful to have 
the "toContainerID" information if the message is being sent to a group 
of containers, for example.

Q: Naming issue: should SharedObjectEvent -> ISharedObjectEvent, since 
it's an interface, not a class?

Q: When ISharedObject.sendMessage() is called, would it be desirable for 
the **sender's** ISharedObject.handleEvent be called as well?  This is 
particularly useful for UI stuff, e.g. putting "message sent!" or 
"message failed - server offline" in a statusbar.  Similarly, for the 
other "send" methods (e.g. sendDispose)?

Under "Example Creation Code"

Q: "org.eclipse.core.events.SharedObjectActivatedEvent" --> 
"org.eclipse.ecf....SharedObjectActivatedEvent"?

Thanks,

Li-Te