Home » Archived » Eclipse Communications Framework (ECF) » ECF documentation comments
ECF documentation comments [message #570630] |
Tue, 14 December 2004 17:51 |
Li-Te Cheng Messages: 16 Registered: July 2009 |
Junior Member |
|
|
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
|
|
| |
Re: ECF documentation comments [message #570818 is a reply to message #570630] |
Wed, 15 December 2004 23:45 |
Scott Lewis Messages: 1038 Registered: July 2009 |
Senior Member |
|
|
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().addSharedObj ect(...)
>
>
> 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
|
|
|
|
|
Goto Forum:
Current Time: Tue Sep 24 03:26:36 GMT 2024
Powered by FUDForum. Page generated in 0.04997 seconds
|