Schmant Task Author's guide

// 
package se.rovarspraket;

// The translator task is a process task. It takes the file from its source
// property, translates it, and puts the result in the location referenced by
// the target property.
//
// The task produces one object (the translated file), which makes it a
// Producer.
//
// Note: This task would have been easier to implement if it had inherited the
// AbstractTextInsertionTask. For pedagogic reasons, it does not.
public final class RobbersLanguageTranslatorTask extends
  AbstractProcessTask<
    RobbersLanguageTranslatorTask> implements
    Producer<WritableFile>
{
  // This ObjectTransformer is used to cast each argument given to the
  // addTranslatedCharacters method into a Character object when flattening the
  // arguments.
  //
  // Inherit from CastingTransformer.
  private static final class CastingToCharacterTransformer
    extends CastingTransformer<Character>
  {
    // Define a singleton instance.
    private static final CastingToCharacterTransformer INSTANCE =
      new CastingToCharacterTransformer();
  }
  
  // The characters that are translated by default
  private static final Set<Character> DEFAULT_TRANSLATED_CHARACTERS =
    new HashSet<Character>(
      Arrays.asList(
        new Character[] { 'b', 'c', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'm', 'n',
          'p', 'q', 'r', 's', 't', 'v', 'w', 'x', 'z' }));
  
  // The vowel that should be inserted. Default is "o".
  private char m_vowel = 'o';
  // A set of characters to translate
  private final Set<Character> m_translatedCharacters = 
    new HashSet<Character>(DEFAULT_TRANSLATED_CHARACTERS);
  
  // The translated file is assigned to this property when the task is run.
  private final AtomicReference<WritableFile> m_produced =
    new AtomicReference<WritableFile>();

  // Make the constructor package private. We want that only the task factory
  // should be able to instantiate this class.
  RobbersLanguageTranslatorTask()
  {
    // Nothing
  }
  
  // This is required by the Producer interface.
  @Override
  public WritableFile get()
  {
    return m_produced.get();
  }
  
  // Setters called by the task factory
  
  void setVowel(char c)
  {
    m_vowel = c;
  }
  
  void addTranslatedCharacter(char c)
  {
    m_translatedCharacters.add(c);
  }
  
  // Add one or several translated characters. This method will flatten the
  // argument into a list.
  void addTranslatedCharacters(Object o)
  {
    // This method is inherited from the AbstractArgumentChecker class. It
    // checks that none of the supplied objects are null
    check(o);
    
    // Flatten the argument by adding it to a FlatteningList.
    FlatteningList<Character> l = new FlatteningList<Character>();
    // Add all arguments. use a custom ObjectTransformer that casts each
    // argument into a Character.
    l.add(o, CastingToCharacterTransformer.INSTANCE);
    
    // Add the flattened argument to the set.
    m_translatedCharacters.addAll(l);
  }
  
  void clearTranslatedCharacters()
  {
    m_translatedCharacters.clear();
  }
  
  // Replace the default, not very good, log header.
  @Override
  protected String getDefaultLogHeader()
  {
    return "Totroranonsoslolatotinongog " + getSource();
  }
  
  // Create the regular expression pattern that is used to replace the text
  private Pattern createPattern()
  {
    StringBuilder sb = new StringBuilder("[");
    for (Character c : m_translatedCharacters)
    {
      sb.append(c);
    }
    // Make the pattern case-insensitive
    return Pattern.compile(
      sb.append("]").toString(),
      Pattern.CASE_INSENSITIVE);
  }
  
  // This method is called from AbstractTask when the task is run.
  @Override
  protected void runInternal(Report r)
  {
    // Interpret the source and target properties.
    // Since the strategy will only return one object, we can call get() to get
	// it.
    ReadableFile source =
      ArgumentInterpreter.getInstance().interpret(
        getSource(),
        InterpretAsReadableFileStrategy.AS_SINGLE).get();
    
    // The target is a new writable file. If there already is a file at the
    // target location, the overwrite strategy decides what to do with it.
    WritableFile target =
      ArgumentInterpreter.getInstance().
        interpret(
          getTarget(),
          new InterpretAsNewWritableFileStrategy(
            getOverwriteStrategy(),
            ArgumentInterpretationStrategy.ALLOW_ONE_AND_ONLY_ONE_RESULT_OBJECT)).
        get();
    
    Pattern pat = createPattern();
    
    // Read the source file to a String and create a Matcher on the string
    String inText = Files.readTextFile(source);
    Matcher mat = pat.matcher(inText);
    
    // The text replacement loop
    StringBuilder res = new StringBuilder();
    int lastMatch = 0;
    while(mat.find())
    {
      // Copy all characters between this match and the previous match
      res.append(inText.substring(lastMatch, mat.start()));
    	
      // The secret substitution...
      res.append(mat.group());
      res.append(m_vowel);
      res.append(mat.group());
    	
      lastMatch = mat.end();
    }
    
    // Copy all trailing characters
    res.append(inText.substring(lastMatch, inText.length()));
    
    // Write the result to the target file
    Files.writeText(target, res.toString());
      
    // The target is our produced object
    m_produced.set(target);
  }
  
  // This method is called when the task (specification) is copied by the task
  // factory. It copies all properties to the new task.
  @Override
  public void copyProperties(RobbersLanguageTranslatorTask spec)
  {
    // We must call this
    super.copyProperties(spec);
    // The character is immutable, so it can safely be copied to the spec
    spec.m_vowel = m_vowel;
    // The list is mutable, so we only copy the list contents, not the list
    // itself.
    spec.m_translatedCharacters.addAll(m_translatedCharacters);
  }
}
//

//
package se.rovarspraket;

public final class RobbersLanguageTranslatorTF extends
  AbstractProcessTaskFactory<
    RobbersLanguageTranslatorTF,
    RobbersLanguageTranslatorTask>
{
  // Setters. All values are set on the task specification, which happens to be
  // the task object itself.

  public RobbersLanguageTranslatorTF setVowel(char c)
  {
    getSpecification().setVowel(c);
    return this;
  }

  public RobbersLanguageTranslatorTF addTranslatedCharacter(char c)
  {
    getSpecification().addTranslatedCharacter(c);
    return this;
  }
  
  // Add a single translated character or an array or a collection of translated
  // characters. The argument will be flattened in
  // RobbersLanguageTranslatorTask.
  public RobbersLanguageTranslatorTF addTranslatedCharacters(Object o)
  {
    getSpecification().addTranslatedCharacters(o);
    return this;
  }
  
  public RobbersLanguageTranslatorTF clearTranslatedCharacters()
  {
    getSpecification().clearTranslatedCharacters();
    return this;
  }
  
  // AbstractTaskFactory wants us to implement this. It
  // is called every time that the task factory needs to create a new
  // TaskSpecification object (which happens to be the Task itself).
  @Override
  protected RobbersLanguageTranslatorTask createSpecification()
  {
    return new RobbersLanguageTranslatorTask();
  }
}
//

enableTaskPackage("se.rovarspraket");

// The source file
var source = new CharSequenceReadableFile("Rhododendron");

// Create the target file in a RAM directory
var target = new FutureFile(
  SchmantFileSystems.createRamFileSystem(),
  "translated.txt");

new dr.RobbersLanguageTranslatorTF().
  setSource(source).
  setTarget(target).
  run();

// Exercise: What does this print?
info(Files.readTextFile(target.getFile()));

// First get the java command to use
// This method invocation gets a "java" or "java.exe" command from:
// a) The Java installation referenced by the JAVA_HOME environment variable, if
//    that is set.
// b) The directories of the PATH environment variable, if that is set.
File javaCmd = JdkUtil.getJdkExecutable("java", "", "exe");

// Create a classpath string from all Jar files found in the extlib directory.

// Our task package.
// The TaskPackageManager class has a static InheritableThreadLocal variable
// containing the task package manager.
TaskPackage tp = TaskPackageManager.
  get().
  getTaskPackage("org.my.task.package");

// Our task package's root directory
Directory tpRoot = tp.getRootDirectory();

Collection<EFile> jarEFiles = Directories.getAllFilesMatching(
  Directories.getDirectory(tpRoot, "extlib"),
  new Glob("*.jar"));

// Make all Jar files File-backed. This is necessary since they are to be used
// by another process.
// The makeFileBacked method copies the file to a temporary directory if it is
// not already File backed. The copy is deleted when the build script
// terminates.
StringBuilder classpath = new StringBuilder();
for (EFile jarEFile : jarEFiles)
{
  classpath.append(
    ECFileResolvableUtil.getFileObject(
      tp.makeFileBacked(jarEFile)).getAbsolutePath());
  classpath.append(File.pathSeparatorChar);
}

// Create an argument list for the process. "true" means that added strings
// containing spaces will be quoted.
ArgumentList al = new ArgumentList(true);

// The program to run
al.add(javaCmd.getAbsolutePath());

// Add the classpath
al.add("-cp").add(classpath.toString());

// Add the class to run
al.add("org.mytask.MyTaskLauncher");

// Save the output from the process to a string
SaveToStringProcessOutputStrategy sos = new SaveToStringProcessOutputStrategy();

// Create a configuration object for the process that we will launch.
ProcessSettings settings = new ProcessSettings().
  setStdoutStrategy(sos).
  setStderrStrategy(sos).
  setArgumentList(al);

// Run the program and wait until it terminates.
ProcessResult result = ProcessSupport.execAndWait(settings);

// Deal with the result...

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE taskdoc SYSTEM "http://www.schmant.org/dtd/tfdoc-1.2.dtd" [
  <!ENTITY taskCategories SYSTEM 
    "http://www.schmant.org/taskref/taskcategories.xmlf">
  <!ENTITY taskFactory SYSTEM 
    "http://www.schmant.org/taskref/TaskFactory.xmlf">
  <!ENTITY generatorTaskFactory SYSTEM 
    "http://www.schmant.org/taskref/GeneratorTaskFactory.xmlf">
]>
<taskdoc>
<!-- Use an external entity reference to a file containing task category
     information. The included file is generated when the task documentation is
     built. -->
&taskCategories;
<!-- Place this task in the text tasks category.
     It would have been nice to be able to call the task package
     "se.rövarspråket" instead, but Java's XML parser could not locate files
     under the se.rövarspråket directory. In the future, when we're all zipping
     around in our flying cars, the whole world will use UTF-8. Sigh.
     (Robbers Language is rövarspråket in Swedish.) -->
<taskfactory 
  name="RobberLanguageTF" 
  package="se.rovarspraket"
  java-package="se.rovarspraket"
  category="catText" 
  entityfs-aware="yes">

<!-- The master detective! -->
<author>Bill Bergson (Kalle Blomkvist)</author>
<since>1.0</since>

<!-- Document this task's restriction. The restriction element is optional. -->
<restriction>This task only works with text files.</restriction>

<!-- Since the task is a process task, it is also an action and a generator
     task. -->
<implements interface="ActionTaskFactory"/>
<implements interface="GeneratorTaskFactory"/>
<implements interface="ProcessTaskFactory"/>

<!-- Use a CDATA block to be able to insert our own HTML formatting. Note the
     link to the target property. If you want to link to a class, use an
     explicit class link like |api:class:(class name)?linkClass=|. See
     ApiLinksTF documentation. -->
<produces><![CDATA[The interpreted value of the
<a href="#RobbersLanguageTF_target">target</a> property.]]></produces>

<short-description>Translate text files to the Robber
  Language.</short-description>

<!-- Note the link to the example. -->
<description><![CDATA[This task translates text files to
<a href="http://en.wikipedia.org/wiki/Rövarspråket">the Robber Language</a>.</p>

<p>The vowel to use when translating can be set in the
<a href="#RobberLanguageTF_vowel">vowel</a> property.</p>

<p>See <a href="#robberLanguageTF_ex_1">this example</a>.]]></description>

<!-- Insert common properties -->
&taskFactory;
&generatorTaskFactory;

<!-- The propertyset element is a container for properties. -->
<propertyset>
<property name="source" required="yes">
  <description>The text file to translate.</description>

  <!-- Document the property's setter method. If the property has several setter
       methods, they can be listed after each other. -->
  <setter-method name="setSource">

  <!-- The setter method description may be omitted if it is obvious what the
       method does. -->
  <description>Set one text file.</description>

  <!-- List all setter method parameters. Note how the interpretation is
       documented. See the documentation for the ArgumentInterpreterLinksTF for
       information on the format of the argument interpreter reference. -->
  <parameter
    name="o" 
    type="Object"
    interpreter="|ai:ai_readable_file;InterpretAsReadableFileStrategy|">A
  text file.</parameter>
  </setter-method>
</property>

<property name="target" required="yes">
  <description>The target location where the translated file will be
  put.</description>

  <setter-method name="setTarget">
  <parameter 
    name="o"
    type="Object"
    interpreter=
      "|ai:ai_new_writable_file;InterpretAsNewWritableFileStrategy|">The
    target file location.</parameter>
  </setter-method>
</property>

<property name="vowel">
  <description>The vowel to use when translating.</description>
  <setter-method name="setVowel">
    <parameter name="c" type="char">The vowel</parameter>
  </setter-method>

  <!-- This property has a default value. -->
  <default-value><![CDATA[<code>o</code>]]></default-value>
</property>

<property name="translatedCharacters">
  <description>The collection of characters that are translated.</description>
  <setter-method name="addTranslatedCharacter">
    <description>Add one translated character.</description>
    <parameter name="c" type="char">The character to translate.</parameter>
  </setter-method>
  <!-- This setter method flattens the argument list. -->
  <setter-method name="addTranslatedCharacters">
    <description>Add one or several translated characters.</description>
    <parameter name="o" type="Object">One character or an
    array or collection of characters.</parameter>
  </setter-method>
  <setter-method name="clearTranslatedCharacters">
    <description>Clear the list of translated characters.</description>
  </setter-method>
</property>

</propertyset>

<examplesintro>For more examples, see somewhere else.</examplesintro>

<example id="robberLanguageTF_ex_1">

  <!-- This description will be used in the examples reference. -->
  <short-description>Translate all files in a directory hierarchy to the Robber
    Language.</short-description>

  <!-- This description is displayed above the example. -->
  <description><![CDATA[Translate all files in the directory hierarchy under
  <code>src</code> to the Robber Language, putting the translated files in a
    directory hierarchy under <code>target</code>.]]></description>

  <!-- Use an include tag to include the example code. The example text will be
       inserted by the IncludeFilesTask when building the documentation.
     
       By keeping examples in separate files, they are made easier to test. -->
  <code>|include:se.rövarspråket/src/doc/taskref/robberLanguageTF_ex1.js|</code>
</example>
</taskfactory>
</taskdoc>