coding/naming/usage conventions for Java Swarm?

[William T. Stockhausen]

Folks,

I've got a couple of very basic questions regarding Swarm's Java API
conventions, brought on in part by Marcus' recent sample code.  While I do a
lot of programming, I'm not a "programmer" per se. Thus, apologies for any
questions where my limited understanding is so muddled that the question
itself makes no sense. Hopefully, a few will make sense.

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

Similarly, many (all?) of the classes appear to have 2 closely-related
versions--one with the "base" name followed by "Impl" (e.g., ScehduleImpl)
and one with the name followed by "CImpl" (e.g., ScheduleCImpl).  The latter
class subclasses from PhaseCImpl, while the former subclasses directly from
java.lang.Object.  Also, the CImpl version allows (apparently) one the power
of the createBegin/createEnd methodology of objectiveC object construction.
        2a. Are there any other features which distiguish the Impl and CImpl
classes?
        2b. What happns when you call createEnd on an instance of a CImpl class?

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

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

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

        return this;
    }

The above snippet raises some additional questions for me regarding CImpl
and Impl classes, as well as object typing:
        3a. scheduleC seems to be used only up to the point where createEnd is
called on it, at which point it returns an instance of Schedule, which is
then manipulated.  I notice this happens some other places, as in main at
        if (randomize)
            {
                SwarmC demoC = new SwarmCImpl (new AddAgentDemo ());
                demoC.createBegin (Globals.env.globalZone);
                demoC.setSynchronizationType (createSyncScheduleType ());
                demo = (AddAgentDemo) demoC.createEnd ();
            }
Is this how you should always deal with instances of a CImpl class?

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


Any insights will be greatly appreciated.

Thanks,

Buck Stockhausen
***********************************************************************
*William T. Stockhausen                     e-mail: address@hidden     *
*Senior Marine Scientist                    voice : 804-684-7643      *
*Virginia Institute of Marine Science       fax   : 804-684-7250      *
*College of William and Mary                http://www.vims.edu/~buck *
*Greate Road                                                          *
*Gloucester Point, VA 23062-1346                                      *
***********************************************************************


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