/ Docs / Introduction

Introduction to SourceFlow

SourceFlow is a source code generation library for Java and .NET. It can be used to create source code files in C, C#, Java or Visual Basic. SourceFlow is not based on templates, but instead creates an object model of the source code to generate in memory. Upon writing this model to disk various style adjustments, such as indentation and reorderings can take place.

This document shows examples using the Java API of SourceFlow. The .NET API is extemely similar and it should be trivial to create the example classes shown here in a language such a C# instead.

Structuring the Output

The best way to use SourceFlow is to have one object that manages each source code file to be generated. Normally this means writing a new class for each type of source code file to generate, but sometimes a single class can be reused for many nearly identical files. In figure 1 below, a simple class for generating a Java source code file is shown.

import org.sourceflow.CodeStyle;
import org.sourceflow.java.*;

class DummyGenerator {

    private static final String CLASS_COMMENT =
        "A dummy class doing nothing of interest.";

    private static final String CONSTR_COMMENT =
        "Initializes this class.";

    private JavaPackage pkg;

    private JavaFile file;

    private JavaClass cls;

    private JavaVariable var;

    private JavaConstructor constr;

    public DummyGenerator(File dir, String pkgName, String name)  {
       // Initialize code objects
       pkg = new JavaPackage(pkgName);
       file = new JavaFile(dir, pkg);
       cls = new JavaClass(JavaClass.PUBLIC, name);
       var = new JavaVariable("ArrayList", "list");
       constr = new JavaConstructor();

       // Connect code objects
       file.addImport(new JavaImport("java.util", "ArrayList"));
       file.addClass(cls);
       cls.addComment(new JavaComment(CLASS_COMMENT));
       cls.addVariable(var);
       cls.addConstructor(constr);
       constr.addComment(new JavaComment(CONSTR_COMMENT));
       constr.addCode(var + " = new ArrayList();");
    }

    ...
}

Figure 1. The Java source code for a simple code generator class using SourceFlow. Note that the file is automatically named according to the base directory, package and name of the first class (or interface) added.

Adding Code Dynamically

The whole point of a library like SourceFlow is to be able to generate source code dynamically. By varying the input data the generated source code can be different in various ways. In figure 2 below this is illustrated by a method that dynamically adds code to the constructor for the code generator class above.

    public void addInitValue(int value) {
        constr.addCode(var + ".add(new Integer(" + value + "));");
    }

Figure 2. A method that dynamically adds source code to the constructor in the generated class.

Handling References

A problem when generating source code is to make sure that all variable and class references are coherent between files. Especially if variable names have to be modified to avoid name clashes or invalid characters, which may be tricky to handle. Using the code structure above makes this much easier to accomplish. In figure 3 below this is illustrated by two additional methods that return references to the class being generated.

    public String getName() {
        return cls.toString();
    }

    public JavaImport getImport() {
        return new JavaImport(pkg, getName());
    }

Figure 3. Two methods that return references to the class being generated. These references can be used in other code generators to create code that compiles correctly.

Writing the Files

When the source code model has been fully created in memory, it can be stored to output files. In figure 4 below this is shown.

    public void write() throws IOException {
        file.write(CodeStyle.JAVA);
    }

Figure 4. An example method for writing the output source code. This method uses the default Java code style instead of creating a customized code style.

Designed & Hosted by Liquid Site Hosting.