Keep it Simple, Simpleton

This document assumes that you've read over the documentation regarding how to install the developer version of Knownspace [Insert Link To Document Here]. In order to successfully program for Knownspace, you'll need the following installed on your machine:

Writing a Simpleton should be as simple as its name implies. Of course, Simpletons don't make hard problems easy, or prove that P=NP or anything like that. Instead, they make it difficult for you to tackle a hard problem all at once. They guide you towards the golden nuggets of software engineering: decomposition, reusability, flexibility, and well, let's face it, true happiness.

If you haven't yet, it might behoove you to review the description of Simpletons in the API design document. Recall that Simpletons are the equivalent of modules or functions in a standard program, with the exception that Simpletons should never become large, monolithic pieces of code. Let's review the rules of Simpletonning:

In short, Simpletons can be seen as Legos - each is small, simple, easily understandable. Individually, they might not have very much clout, but in collaboration they are powerful enough to build very complex structures once you get enough of them going and have a large enough core set. We strive to one-up even Legos, however, as we constantly work towards making Simpletons more easily replaceable - how hard would it be to remove the center lego out of a castle of legos? How hard should it be to swap in a Simpleton that deals with downloading POP mail instead of IMAP mail?

So let's begin with the equivalent of a "Hello World" Simpleton. First of all, there is a sort of boilerplate you must follow when you write a Simpleton. In your class definition, begin by importing the Simpleton abstract class from the org.datamanager.kernel package like so:

import org.datamanager.kernel.Simpleton;

Then, your class declaration must extend the Simpleton abstract class, i.e.,

public class FooSimpleton extends Simpleton {

One immediate difference you'll notice between writing Simpleton-s and other Java classes is that you don't need to specify a constructor - in fact, you don't want to specify a constructor. The Knownspace Kernel deals with Simpleton creation and startup and hides away all of the other details. We'll go over how to let Knownspace figure out how to load your Simpletons shortly.

Constructors, Schmonfuctors

Instead of a constructor, the Simpleton abstract class defines an abstract public void process() method that all Simpletons must override. It is within this method that any set up initialization must occur. In other words, in lieu of placing set up code that makes sure your Simpleton starts up in a proper state within a constructor, just drop it in the process() method. If you are at this moment thinking, "Well, damnit, that's a huge limitation on what I can or cannot do with Object Oriented Programming", rest assured, the need for customizable construction of these Simpletons is entirely unnecessary - remember, the goal of a Simpleton is to act as an assembly line worker. It doesn't need to know about the other assembly line workers to do its job, in fact, it follows the XP mantra of trust thy neighbor, and trusts its fellow Simpletons to do the right thing, and, correspondingly, strives to do the right thing itself. Simpletons should not have to be tightly coupled with their creator by having special parameters required during Simpleton construction - if you believe this to be the case, decouple it from your design and create multiple Simpletons, one for each type of Simpleton you wish to construct. This is just part of the way Knownspace helps to guide you towards the Loose Coupling Way (tm). All of this will make more sense also by the time you get to the end of this tutorial.

So let's create a very simple GUI Simpleton that displays the text "Hellooooo, Helium!".

We begin with our boilerplate and a package statement signifying where our Simpleton class should be placed. Then, we just add some simple Swing code to display a JTextField and we're done with this admittedly contrived example. 


package org.datamanager.simpleton;

import org.datamanager.kernel.Simpleton;

import javax.swing.JFrame;
import javax.swing.JTextField;

public class HelloHeliumSimpleton extends Simpleton {
    public void process() {
        final JFrame frame = new JFrame("Helium Huffers Unite");
        frame.getContentPane().add(new JTextField("Hellooooo, Helium!"));
        // display the frame
        frame.pack();
        frame.setVisible(true);
    }
}

So now we've created the tried-and-true "Hello, Cliche!" test program! I bet you're all just burning to figure out how to run it, eh? So since you're in the developer portion of this site, you've probably heard of this little secret we in the business like to call 'XML'. XML is what computer scientists invented in their spare time once they realized that hardware had progressed to a point where they (the computer scientists, not the hardware) could waste a whole lot more space. It is a flexible and descriptive way to store data. In any case, the knownspace_config.xml file at the top level of the helium package you should have already downloaded from here contains all the information you'll need to start running your own Simpletons and Simpletonnettes.

GUI Simpleton Configuration

There will be a configuration GUI available soon.

Manually modify the knownspace_config.xml file

Open up the knownspace_config.xml in your favorite editor and poke around. You'll notice that there are two types of elements right below the Config element in the XML document - these are the <UserInterface> and <Simpleton> elements. For now, there isn't very to distinguish between the two yet - the only place where they are delineated is in the KernelGui that pops up when you invoke an 'ant run' on your system.

Next, we take a more in-depth look at creating Simpletons that actually interact with the rest of Knownspace. Go to part two of the tutorial!