Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » Eclipse Communications Framework (ECF) » ECF documentation comments
ECF documentation comments [message #570630] Tue, 14 December 2004 17:51 Go to next message
Li-Te Cheng is currently offline 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 #570752 is a reply to message #570630] Wed, 15 December 2004 11:54 Go to previous messageGo to next message
Pete Mackie is currently offline Pete Mackie
Messages: 8
Registered: July 2009
Junior Member
Li-Te wrote:
> 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.
>

The newsgroup URL now reads: eclipse.technology.ecf

Thank you for pointing out this error.

Pete Mackie
Re: ECF documentation comments [message #570818 is a reply to message #570630] Wed, 15 December 2004 23:45 Go to previous message
Scott Lewis is currently offline Scott Lewis
Messages: 971
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
Previous Topic:Cannot access ECF CVS
Next Topic:one suggest.
Goto Forum:
  


Current Time: Sat Oct 25 19:54:41 GMT 2014

Powered by FUDForum. Page generated in 0.10714 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software