Re: coding/naming/usage conventions for Java Swarm?

[Marcus G. Daniels]

>>>>> "WS" == William T Stockhausen <address@hidden> writes:

WS> Many (all?) of the java interfaces appear to have 3
WS> closely-related versions--one with just the name (e.g., Schedule),
WS> one with a "C" appended to the base name (e.g. ScheduleC) and one
WS> with an "S" appended to the base name (e.g., ScheduleS).  1a. What
WS> distinguishes whether an interface should be name, nameC, or
WS> nameS?

The simplest name with no suffix is the `Using' phase Java interface.
Java interfaces, unlike classes, don't have instance variables or
inheritance of state, but just describe how to talk to an object.  In
most models, 90% of the code will use `Using' phase constructors that
look like any other Java constructor, except that they have a first
argument of a Zone.

"C" means `Creating', which are interfaces that have the methods for
configuring an object (once configured, it is in `Using' phase).
The Using phase constructor calls the default `Creating' phase
constructor and then does the switch for you. 

"S" means `Setting', which are interfaces that have methods that work
equally well when configuring the object or when using it.  Something
like setting the color of an object could be a Setting phase feature
because you could make an object blue at create time or change the
color of an object once it was on the screen.  However, stating that
you need an Schedule that randomizes is a structural decision and thus
permanent.

In the code posted, there are some usages of Creating interfaces and
classes that are necessary because there are not Using phase
constructors that encapsulate the particular usage.  These cases exist
either because the usage is unusual and thus didn't motivate the
addition of these setup shortcuts, or because the usage is too complex
to capture as a constructor (a lot of parameters, or mechanical things
that have to happen during the setup).

WS> Similarly, many (all?) of the classes appear to have 2
WS> closely-related versions--one with the "base" name followed by
WS> "Impl" (e.g., ScehduleImpl) and one with the name followed by
WS> "CImpl" (e.g., ScheduleCImpl).  The latter class subclasses from
WS> PhaseCImpl, while the former subclasses directly from
WS> java.lang.Object.  Also, the CImpl version allows (apparently) one
WS> the power of the createBegin/createEnd methodology of objectiveC
WS> object construction. 

Right, the "base" names are the interfaces and the "Impl" names are
the classes that implement them.  Sometimes it is desirable to use a
general interface name to reference a specific kind of object for
flexibility.  For example, either a HDF5ArchiverImpl or
LispArchiverImpl instance can be assigned to a variable like "Archiver
archiver".  That makes it easy to change implementations (e.g. trading
off, say, ease-of-use and efficiency) and not touch the code that
calls on it.

WS> 2a. Are there any other features which distiguish the Impl and
WS> CImpl classes? 

The CImpl classes/constructors really just facilitate connecting
multiple typed Java objects to single dynamically typed Objective C objects.

WS> 2b. What happns when you call createEnd on an instance of a CImpl
WS> class?

It looks to see what object will be used for the next phase on the Java side,
and associates that object with the object just updated (or re-created) on
the Objective C by -createEnd.  

WS> The examples that I've looked at up to now avoid the CImpl route
WS> (e.g., Charles Staelin's very nice jSWARM Tutorial)

Yeah, the phase switching takes some getting used to, and most of the
time it isn't needed at all.

WS> The examples that I've looked at up to now avoid the CImpl route
WS> (e.g., Charles Staelin's very nice jSWARM Tutorial), or I just
WS> haven't noticed a difference between how Impl and Cimpl classes
WS> are used.  However, in Marcus' recent example code (AddAgentDemo),
WS> he seems to treat the two differently, as in the following code
WS> snippet from the BabyAgent class methods:

MD>    public Object buildActions () {
MD>        super.buildActions ();

MD>        ScheduleC scheduleC = new ScheduleCImpl (new ScheduleImpl ());
MD>        scheduleC.createBegin (getZone ());
MD>        scheduleC.setRelativeTime (true);
MD>        scheduleC.setRepeatInterval (9);
MD>        schedule = (Schedule) scheduleC.createEnd ();

MD>        schedule.at$createFAction (2, createCall ("stepAgent"));

MD>        return this;
MD>    }


WS> The above snippet raises some additional questions for me regarding CImpl
WS> and Impl classes, as well as object typing:

WS>     3a. scheduleC seems to be used only up to the point where createEnd is
WS> called on it, at which point it returns an instance of Schedule, which is
WS> then manipulated. 
[..]
WS> Is this how you should always deal with instances of a CImpl class?

Once the Using phase object is instantiated (assigned from createEnd), 
the creating phase object should not be used.  I just used a variable
to avoid giant expressions.  I suppose it would be best to put { } around
such clauses to clarify this, but that just meant more cluttery indenting.

WS>     3b. In the first snippet, scheduleC is apparently an instance
WS> of ScheduleC, not ScheduleCImpl, while schedule is an instance of
WS> Schedule (not, perhaps, ScheduleImpl).  Is this general? I.e., if the
WS> implementation is NameImpl, then an instance created by this class has
WS> class Name? Or am I confusing classes and interfaces here, so that
WS> this is really saying that scheduleC (schedule) is an instance of a
WS> class which must implement the ScheduleC (Schedule) interface?

It's general for all classes in library packages (swarm.*.*).  You
could use the Impl instead, but that is saying more than needs to
said.  An Impl would let you touch public variables, for example.  The
non-Impl just says that the object in questions responds to certain
methods.  Both would work here.


                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.