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

[Scott Lewis <slewis@xxxxxxxxxxxxx>]

Li-Te wrote:
<stuff deleted>

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

Yes, this is a typo...I have fixed and checked in fix to 
eclipse.org...it (and the other typo you point to below) should be fixed 
on the eclipse.org site shortly.  Thanks for pointing these out.

>
> "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.


I think that in classes that implement ISharedObject the answer is 
absolutely 'yes'.  I would tend to make this a protected (subclasses 
only) method...e.g. protected void getConfig().

But I'm not sure it belongs in the ISharedObject interface because the 
ISharedObject interface defines an *external* contract that an 
ISharedObject has to satisfy (to it's container).  And the container is 
the source of the ISharedObjectConfig instance, so it doesn't really 
need a 'getConfig()' on ISharedObject.

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


Hmmm.  I don't think so...here's my thinking...the ISharedObject 
reference is really for the container to use to manage the shared 
object.  The container controls/manages the initialization, and so 
doesn't need to check whether the shared object is initialized.  It 
could/should probably be in a top-level class that implements 
ISharedObject though...certainly for convenience of access internal to 
the ISharedObject (and possibly to provide access to other objects).


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


The intention was to provide an event that notifies the shared object 
(and other shared objects that are interested) of the fact that a shared 
object has been initialized and now is activated (a state that suggests 
not only successful initialization, but also *existence* in the 
container relative to other shared objects.

>
>
> 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?

Yes.  I'll fix...thanks.  It should/will read:

ISharedObjectContainer.getSharedObjectManager().addSharedObject(...)

>
>
> 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"?

"send like email".  The event is actually sent with a thread separate 
from the one that calls init...at least providers have the discretion to 
implement it that way.

>
> 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.

This seems reasonable.  We'll refactor these event class/interface 
relationships accordingly.


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

Yes.  Typo...thanks.  We'll fix (probably this evening when refactoring 
the event interfaces and classes.

>
> 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)?

Perhaps...but OTOH, such code might be more appropriately written in the 
 exception handler for the sendMessage IOException...e.g.

try {
	getContext().sendMessage(...);
} catch (IOException e) {
	// put "server offline" message to UI here
}


>
> Under "Example Creation Code"
>
> Q: "org.eclipse.core.events.SharedObjectActivatedEvent" --> 
"org.eclipse.ecf....SharedObjectActivatedEvent"?

Yes, this is also a type.  It's fixed now...thanks!

Scott