Writing a custom Target

When the existing functionality is not enough, you can implement your own target.

Target with ingredients

Let's define a custom target that sums the sizes of (the cached contents of) given paths. First we will write a naive implementation that just uses the cached contents of other paths without declaring them ingredients.

package com.example.wsdef;

import java.util.Arrays;

import java.util.List;

import org.fluentjava.iwant.api.core.HelloTarget;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.SideEffect;

import org.fluentjava.iwant.api.model.Target;

import org.fluentjava.iwant.api.wsdef.SideEffectDefinitionContext;

import org.fluentjava.iwant.api.wsdef.TargetDefinitionContext;

import org.fluentjava.iwant.api.wsdef.Workspace;

import org.fluentjava.iwant.eclipsesettings.EclipseSettings;

public class IwanttutorialWorkspace implements Workspace {

private final Path ingredient1 = new HelloTarget("ingredient1", "12");

private final Path ingredient2 = new HelloTarget("ingredient2", "345");

private final Target myTarget = new FileSizeSum("file-size-sum",

Arrays.asList(ingredient1, ingredient2));

@Override

public List<? extends Target> targets(TargetDefinitionContext ctx) {

return Arrays.asList(new HelloTarget("hello", "hello from iwant\n"));

return Arrays.asList(new HelloTarget("hello", "hello from iwant\n"),

myTarget);

}

@Override

public List<? extends SideEffect> sideEffects(

SideEffectDefinitionContext ctx) {

return Arrays.asList(EclipseSettings.with().name("eclipse-settings")

.modules(ctx.wsdefdefJavaModule(), ctx.wsdefJavaModule())

.end());

}

package com.example.wsdef;

import java.io.File;

import java.util.List;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.TargetEvaluationContext;

import org.fluentjava.iwant.api.target.TargetBase;

import org.fluentjava.iwant.coreservices.FileUtil;

class FileSizeSum extends TargetBase {

private final List<Path> pathsToSum;

public FileSizeSum(String name, List<Path> pathsToSum) {

super(name);

this.pathsToSum = pathsToSum;

}

@Override

protected IngredientsAndParametersDefined ingredientsAndParameters(

IngredientsAndParametersPlease iUse) {

return iUse.nothingElse();

}

@Override

public void path(TargetEvaluationContext ctx) throws Exception {

File dest = ctx.cached(this);

System.err.println("Refreshing " + dest);

int pathSizeSum = 0;

for (Path path : pathsToSum) {

File pathFile = ctx.cached(path);

int pathSize = FileUtil.contentAsBytes(pathFile).length;

pathSizeSum += pathSize;

}

FileUtil.newTextFile(dest, pathSizeSum + "\n");

}

~/iwant-tutorial $ as-iwant-tutorial-developer/with/bash/iwant/target/file-size-sum/as-path | xargs -r find (0/1 D! com.example.wsdef.FileSizeSum file-size-sum) Refreshing /home/hacker/iwant-tutorial/as-iwant-tutorial-developer/.i-cached/target/file-size-sum (FAILED com.example.wsdef.FileSizeSum file-size-sum) Target file-size-sum referred to ingredient1 without declaring it an ingredient.

The context iwant passes to our target allows us to resolve a path to a file that contains its cached content. But if we haven't declared the referred path an ingredient, iwant will throw an exception.

package com.example.wsdef;

import java.io.File;

import java.util.List;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.TargetEvaluationContext;

import org.fluentjava.iwant.api.target.TargetBase;

import org.fluentjava.iwant.coreservices.FileUtil;

class FileSizeSum extends TargetBase {

private final List<Path> pathsToSum;

public FileSizeSum(String name, List<Path> pathsToSum) {

super(name);

this.pathsToSum = pathsToSum;

}

@Override

protected IngredientsAndParametersDefined ingredientsAndParameters(

IngredientsAndParametersPlease iUse) {

return iUse.nothingElse();

return iUse.ingredients("pathsToSum", pathsToSum).nothingElse();

}

@Override

public void path(TargetEvaluationContext ctx) throws Exception {

File dest = ctx.cached(this);

System.err.println("Refreshing " + dest);

int pathSizeSum = 0;

for (Path path : pathsToSum) {

File pathFile = ctx.cached(path);

int pathSize = FileUtil.contentAsBytes(pathFile).length;

pathSizeSum += pathSize;

}

FileUtil.newTextFile(dest, pathSizeSum + "\n");

}

~/iwant-tutorial $ as-iwant-tutorial-developer/with/bash/iwant/target/file-size-sum/as-path | xargs -r cat (0/1 S~ org.fluentjava.iwant.api.javamodules.JavaClasses iwant-tutorial-wsdef-main-classes) (0/1 D! org.fluentjava.iwant.api.core.HelloTarget ingredient1) (0/1 D! org.fluentjava.iwant.api.core.HelloTarget ingredient2) (0/1 D! com.example.wsdef.FileSizeSum file-size-sum) Refreshing /home/hacker/iwant-tutorial/as-iwant-tutorial-developer/.i-cached/target/file-size-sum 5

Now that we declared the ingredients, iwant automatically told them to refresh their cached contents before telling our target to refresh its. We can see this from the output. The D! before a target's type and name means the target is refreshed because its cached content descriptor (and thus also its content) is missing.

(We can also see that the workspace definition classes were updated. The S~ in the output means they were updated because of modified source ingredients. We just modified the source of our target, a part of the workspace definition.)

iwant uses a target's cached content descriptor and its timestamp to determine whether the target is dirty (needs refreshing) or up-to-date. We as target authors just defined the content descriptor in the method ingredientsAndParameters.

Target with parameters

Next we will make our target accept static input, a parameter. We will add a header line above the size sum line. Again, we first try what happens if we don't declare this change to our content definition.

package com.example.wsdef;

import java.util.Arrays;

import java.util.List;

import org.fluentjava.iwant.api.core.HelloTarget;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.SideEffect;

import org.fluentjava.iwant.api.model.Target;

import org.fluentjava.iwant.api.wsdef.SideEffectDefinitionContext;

import org.fluentjava.iwant.api.wsdef.TargetDefinitionContext;

import org.fluentjava.iwant.api.wsdef.Workspace;

import org.fluentjava.iwant.eclipsesettings.EclipseSettings;

public class IwanttutorialWorkspace implements Workspace {

private final Path ingredient1 = new HelloTarget("ingredient1", "12");

private final Path ingredient2 = new HelloTarget("ingredient2", "345");

private final Target myTarget = new FileSizeSum("file-size-sum",

Arrays.asList(ingredient1, ingredient2));

Arrays.asList(ingredient1, ingredient2), "The sum");

@Override

public List<? extends Target> targets(TargetDefinitionContext ctx) {

return Arrays.asList(new HelloTarget("hello", "hello from iwant\n"),

myTarget);

}

@Override

public List<? extends SideEffect> sideEffects(

SideEffectDefinitionContext ctx) {

return Arrays.asList(EclipseSettings.with().name("eclipse-settings")

.modules(ctx.wsdefdefJavaModule(), ctx.wsdefJavaModule())

.end());

}

package com.example.wsdef;

import java.io.File;

import java.util.List;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.TargetEvaluationContext;

import org.fluentjava.iwant.api.target.TargetBase;

import org.fluentjava.iwant.coreservices.FileUtil;

class FileSizeSum extends TargetBase {

private final List<Path> pathsToSum;

private final String headerLineContent;

public FileSizeSum(String name, List<Path> pathsToSum) {

public FileSizeSum(String name, List<Path> pathsToSum,

String headerLineContent) {

super(name);

this.pathsToSum = pathsToSum;

this.headerLineContent = headerLineContent;

}

@Override

protected IngredientsAndParametersDefined ingredientsAndParameters(

IngredientsAndParametersPlease iUse) {

return iUse.ingredients("pathsToSum", pathsToSum).nothingElse();

}

@Override

public void path(TargetEvaluationContext ctx) throws Exception {

File dest = ctx.cached(this);

System.err.println("Refreshing " + dest);

int pathSizeSum = 0;

for (Path path : pathsToSum) {

File pathFile = ctx.cached(path);

int pathSize = FileUtil.contentAsBytes(pathFile).length;

pathSizeSum += pathSize;

}

FileUtil.newTextFile(dest, pathSizeSum + "\n");

FileUtil.newTextFile(dest,

headerLineContent + "\n" + pathSizeSum + "\n");

}

Whoops, cache invalidation! Unfortunately, at the moment iwant cannot help, if the target author forgets to declare a parameter i.e. input that is not a reference to another path, an ingredient.

package com.example.wsdef;

import java.io.File;

import java.util.List;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.TargetEvaluationContext;

import org.fluentjava.iwant.api.target.TargetBase;

import org.fluentjava.iwant.coreservices.FileUtil;

class FileSizeSum extends TargetBase {

private final List<Path> pathsToSum;

private final String headerLineContent;

public FileSizeSum(String name, List<Path> pathsToSum,

String headerLineContent) {

super(name);

this.pathsToSum = pathsToSum;

this.headerLineContent = headerLineContent;

}

@Override

protected IngredientsAndParametersDefined ingredientsAndParameters(

IngredientsAndParametersPlease iUse) {

return iUse.ingredients("pathsToSum", pathsToSum).nothingElse();

return iUse.ingredients("pathsToSum", pathsToSum)

.parameter("headerLineContent", headerLineContent)

.nothingElse();

}

@Override

public void path(TargetEvaluationContext ctx) throws Exception {

File dest = ctx.cached(this);

System.err.println("Refreshing " + dest);

int pathSizeSum = 0;

for (Path path : pathsToSum) {

File pathFile = ctx.cached(path);

int pathSize = FileUtil.contentAsBytes(pathFile).length;

pathSizeSum += pathSize;

}

FileUtil.newTextFile(dest,

headerLineContent + "\n" + pathSizeSum + "\n");

}

~/iwant-tutorial $ as-iwant-tutorial-developer/with/bash/iwant/target/file-size-sum/as-path | xargs -r cat (0/1 S~ org.fluentjava.iwant.api.javamodules.JavaClasses iwant-tutorial-wsdef-main-classes) (0/1 D~ com.example.wsdef.FileSizeSum file-size-sum) Refreshing /home/hacker/iwant-tutorial/as-iwant-tutorial-developer/.i-cached/target/file-size-sum The sum 5

But if we change the value of the parameter, the target will become dirty and be refreshed.

package com.example.wsdef;

import java.util.Arrays;

import java.util.List;

import org.fluentjava.iwant.api.core.HelloTarget;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.SideEffect;

import org.fluentjava.iwant.api.model.Target;

import org.fluentjava.iwant.api.wsdef.SideEffectDefinitionContext;

import org.fluentjava.iwant.api.wsdef.TargetDefinitionContext;

import org.fluentjava.iwant.api.wsdef.Workspace;

import org.fluentjava.iwant.eclipsesettings.EclipseSettings;

public class IwanttutorialWorkspace implements Workspace {

private final Path ingredient1 = new HelloTarget("ingredient1", "12");

private final Path ingredient2 = new HelloTarget("ingredient2", "345");

private final Target myTarget = new FileSizeSum("file-size-sum",

Arrays.asList(ingredient1, ingredient2), "The sum");

Arrays.asList(ingredient1, ingredient2), "The sum of file sizes");

@Override

public List<? extends Target> targets(TargetDefinitionContext ctx) {

return Arrays.asList(new HelloTarget("hello", "hello from iwant\n"),

myTarget);

}

@Override

public List<? extends SideEffect> sideEffects(

SideEffectDefinitionContext ctx) {

return Arrays.asList(EclipseSettings.with().name("eclipse-settings")

.modules(ctx.wsdefdefJavaModule(), ctx.wsdefJavaModule())

.end());

}

~/iwant-tutorial $ as-iwant-tutorial-developer/with/bash/iwant/target/file-size-sum/as-path | xargs -r cat (0/1 S~ org.fluentjava.iwant.api.javamodules.JavaClasses iwant-tutorial-wsdef-main-classes) (0/1 D~ com.example.wsdef.FileSizeSum file-size-sum) Refreshing /home/hacker/iwant-tutorial/as-iwant-tutorial-developer/.i-cached/target/file-size-sum The sum of file sizes 5

The D~ in the output means the target was refreshed because of a changed content descriptor. Out of curiosity, let's see what our content descriptor now looks like.

Target under construction

When developing a target, it is convenient to declare its own source an ingredient. This way any change to its source makes it dirty. If the target uses other classes, they or their classes also need to be declared.

package com.example.wsdef;

import java.io.File;

import java.util.List;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.Source;

import org.fluentjava.iwant.api.model.TargetEvaluationContext;

import org.fluentjava.iwant.api.target.TargetBase;

import org.fluentjava.iwant.core.javafinder.WsdefJavaOf;

import org.fluentjava.iwant.coreservices.FileUtil;

class FileSizeSum extends TargetBase {

private final List<Path> pathsToSum;

private final String headerLineContent;

private final Source me;

public FileSizeSum(String name, List<Path> pathsToSum,

String headerLineContent) {

String headerLineContent, WsdefJavaOf wsdefJavaOf) {

super(name);

this.pathsToSum = pathsToSum;

this.headerLineContent = headerLineContent;

this.me = wsdefJavaOf.classUnderSrcMainJava(getClass());

}

@Override

protected IngredientsAndParametersDefined ingredientsAndParameters(

IngredientsAndParametersPlease iUse) {

return iUse.ingredients("pathsToSum", pathsToSum)

.parameter("headerLineContent", headerLineContent)

.nothingElse();

.ingredients("me", me).nothingElse();

}

@Override

public void path(TargetEvaluationContext ctx) throws Exception {

File dest = ctx.cached(this);

System.err.println("Refreshing " + dest);

int pathSizeSum = 0;

for (Path path : pathsToSum) {

File pathFile = ctx.cached(path);

int pathSize = FileUtil.contentAsBytes(pathFile).length;

pathSizeSum += pathSize;

}

FileUtil.newTextFile(dest,

headerLineContent + "\n" + pathSizeSum + "\n");

}

package com.example.wsdef;

import java.util.Arrays;

import java.util.List;

import org.fluentjava.iwant.api.core.HelloTarget;

import org.fluentjava.iwant.api.model.Path;

import org.fluentjava.iwant.api.model.SideEffect;

import org.fluentjava.iwant.api.model.Target;

import org.fluentjava.iwant.api.wsdef.SideEffectDefinitionContext;

import org.fluentjava.iwant.api.wsdef.TargetDefinitionContext;

import org.fluentjava.iwant.api.wsdef.Workspace;

import org.fluentjava.iwant.api.wsdef.WorkspaceContext;

import org.fluentjava.iwant.core.javafinder.WsdefJavaOf;

import org.fluentjava.iwant.eclipsesettings.EclipseSettings;

public class IwanttutorialWorkspace implements Workspace {

private final Path ingredient1 = new HelloTarget("ingredient1", "12");

private final Path ingredient2 = new HelloTarget("ingredient2", "345");

private final Target myTarget = new FileSizeSum("file-size-sum",

Arrays.asList(ingredient1, ingredient2), "The sum of file sizes");

private final Target myTarget;

public IwanttutorialWorkspace(WorkspaceContext ctx) {

myTarget = new FileSizeSum("file-size-sum",

Arrays.asList(ingredient1, ingredient2),

"The sum of file sizes", new WsdefJavaOf(ctx));

}

@Override

public List<? extends Target> targets(TargetDefinitionContext ctx) {

return Arrays.asList(new HelloTarget("hello", "hello from iwant\n"),

myTarget);

}

@Override

public List<? extends SideEffect> sideEffects(

SideEffectDefinitionContext ctx) {

return Arrays.asList(EclipseSettings.with().name("eclipse-settings")

.modules(ctx.wsdefdefJavaModule(), ctx.wsdefJavaModule())

.end());

}

package com.example.wsdef;

import org.fluentjava.iwant.api.wsdef.Workspace;

import org.fluentjava.iwant.api.wsdef.WorkspaceContext;

import org.fluentjava.iwant.api.wsdef.WorkspaceFactory;

public class IwanttutorialWorkspaceFactory implements WorkspaceFactory {

@Override

public Workspace workspace(WorkspaceContext ctx) {

return new IwanttutorialWorkspace();

return new IwanttutorialWorkspace(ctx);

}

~/iwant-tutorial $ as-iwant-tutorial-developer/with/bash/iwant/target/file-size-sum/as-path | xargs -r cat (0/1 S~ org.fluentjava.iwant.api.javamodules.JavaClasses iwant-tutorial-wsdef-main-classes) (0/1 D~ com.example.wsdef.FileSizeSum file-size-sum) Refreshing /home/hacker/iwant-tutorial/as-iwant-tutorial-developer/.i-cached/target/file-size-sum The sum of file sizes 5

~/iwant-tutorial $ as-iwant-tutorial-developer/with/bash/iwant/target/file-size-sum/as-path | xargs -r cat (0/1 S~ org.fluentjava.iwant.api.javamodules.JavaClasses iwant-tutorial-wsdef-main-classes) (0/1 S~ com.example.wsdef.FileSizeSum file-size-sum) Refreshing /home/hacker/iwant-tutorial/as-iwant-tutorial-developer/.i-cached/target/file-size-sum The sum of file sizes 5