Join Zen's Slack

Java

The Java API for the Pebble Stream Runtime

Suggest Edits

Here's an example of running a pebble and printing the results using the Java runtime API:

import com.pebblestream.runtime.PebbleStreamRuntime;
import com.pebblestream.runtime.PebbleContext;

import java.util.Map;

public class Example {
	public static void main(String[] args) {

		// runPbl
		System.out.println("runPbl");
		Map<String,Object[][]> result = PebbleStreamRuntime.runPbl(new PebbleContext.Builder()
				.pbl("path/to/my/test.pbl")
				.pblId(42)
				.bigDecimal(true)
				.build()
			);
		for (Map.Entry<String,Object[][]> entry: result.entrySet()) {
			System.out.println(entry.getKey() + ":");
			Object[][] rows = entry.getValue();
			for (int i=0; i<rows.length; i++) {
				for (int j=0; j<rows[i].length; j++) System.out.print((j>0?" | ":"")+rows[i][j].toString());
				System.out.println();
			}
			System.out.println();
		}
	}
}

The PebbleStreamRuntime exposes several static methods which are the entry points into the Pebble Stream runtime. To call these methods, most expect a PebbleContext, which is basically an object with a bunch of optional fields set on it. You create these using the PebbleContext.Builder class. (Note: the PebbleContext is not to be confused with an 'output context', which is an opaque Java Object returned by runPblReturnOutputContext.)

PebbleStreamRuntime

The PebbleStreamRuntime class contains several static methods which are how you use the API. Most expect a PebbleContext as an argument.

contextToColumns

Map<String,Object[][]> contextToColumns(Object outputContext)
Given the output context returned by runPblReturnOutputContext, give back a map of output sheet name to column-wise grid of values.

Object outputContext = PebbleStreamRuntime.runPblReturnOutputContext(new PebbleContext.Builder()
		.pbl("test.pbl")
		.pblId(42)
		.build()
	);
Map<String,Object[][]> colsCtx = PebbleStreamRuntime.contextToColumns(outputContext);
for (Map.Entry<String,Object[][]> entry: colsCtx.entrySet()) {
	System.out.println(entry.getKey() + ":");
	Object[][] cols = entry.getValue();
	for (int i=0; i<cols.length; i++) {
		for (int j=0; j<cols[i].length; j++) System.out.print((j>0?" | ":"")+cols[i][j].toString());
		System.out.println();
	}
	System.out.println();
}

contextToRows

Map<String,Object[][]> contextToRows(Object outputContext)
Given the output context returned by runPblReturnOutputContext, give back a map of output sheet name to row-wise grid of values.

		Object outputContext = PebbleStreamRuntime.runPblReturnOutputContext(new PebbleContext.Builder()
				.pbl("test.pbl")
				.pblId(42)
				.build()
			);
		Map<String,Object[][]> rowsCtx = PebbleStreamRuntime.contextToRows(outputContext);
		for (Map.Entry<String,Object[][]> entry: rowsCtx.entrySet()) {
			System.out.println(entry.getKey() + ":");
			Object[][] rows = entry.getValue();
			for (int i=0; i<rows.length; i++) {
				for (int j=0; j<rows[i].length; j++) System.out.print((j>0?" | ":"")+rows[i][j].toString());
				System.out.println();
			}
			System.out.println();
		}

contextToCellsComputed

Map<String,Long> contextToCellsComputed(Object outputContext)
Given the pebble context returned by runPblReturnOutputContext, give back a map from sheet name to the number of cells computed in that sheet.

    Object outputContext = runPblReturnOutputContext(new PebbleContext.Builder()
        .pbl("test.pbl")
        .pblId(42)
        .build()
      );
    Map<String,Long> sheetToCellsComputed = contextToCellsComputed(outputContext);
    for (Map.Entry<String,Long> entry: sheetToCellsComputed.entrySet()) {
      System.out.println(entry.getKey() + ": " + entry.getValue());
    }

contextToError

RunPblError contextToError(Object outputContext)
Given the pebble context returned by runPblReturnOutputContext, if an error occurred, return a RunPblError describing the error.

    Object outputContext = runPblReturnOutputContext(new PebbleContext.Builder()
        .pbl("test.pbl")
        .pblId(42)
        .build()
      );
    RunPblError error = contextToError(outputContext);
    if (error == null) System.out.println("(null)");
    else {
      System.out.println("Error: " + error.error);
      System.out.println("Address: " + error.address);
      System.out.println("Exception: " + (error.exception==null?null:error.exception.getMessage())
    }

contextToExecutionTime

Map<String,Long> contextToExecutionTime(Object outputContext)
Given the pebble context returned by runPblReturnOutputContext, give back a map from sheet name to the number of milliseconds spent computing it.

    Object outputContext = runPblReturnOutputContext(new PebbleContext.Builder()
        .pbl("test.pbl")
        .pblId(42)
        .build()
      );
    Map<String,Long> sheetToExecutionTime = contextToExecutionTime(outputContext);
    for (Map.Entry<String,Long> entry: sheetToExecutionTime.entrySet()) {
      System.out.println(entry.getKey() + ": " + entry.getValue());
    }

contextToWarnings

Address[] contextToWarnings(Object outputContext)
Given the pebble context returned by runPblReturnOutputContext, give back a list of Addresses which triggered a warning.

    Object outputContext = runPblReturnOutputContext(new PebbleContext.Builder()
        .pbl("test.pbl")
        .pblId(42)
        .build()
      );
    Address[] warnings = contextToWarnings(outputContext);
    for (int i=0; i<warnings.length; i++) System.out.println(warnings[i]);

describeInputsAndOutputs

PebbleStreamRuntime.PblIoDescription describeInputsAndOutputs(PebbleContext context)

PebbleContext options: pblId (required), pbl, reload

Returns a PblIoDescription object, which has this structure (as an example):

PblIoDescription {
  .inputs [
    SheetIoDescription {
      .name "Sheet1"
      .columns [
        ColumnIoDescription {
          .headers ["Count"]
          .types {ColumnIoDescriptionType.NUMBER}
        },
        ColumnIoDescription {
          .headers ["Enrolled"]
          .types {ColumnIoDescriptionType.BOOLEAN}
        },
        ColumnIoDescription {
          .headers ["Count"]
          .types {ColumnIoDescriptionType.BLANK, ColumnIoDescriptionType.NUMBER}
        }
      ]
    }
    ...
  ]
  .outputs [ <same idea> ]

where "inputs" is the sheets which have no dependencies, and "outputs" is the union of 'final' worksheets (those with no dependents) and those set with the pebblestream:out directive. Their order is as in the original file.

PblIoDescription descPbl = PebbleStreamRuntime.describeInputsAndOutputs(new PebbleContext.Builder()
		.pbl("test.pbl")
		.pblId(42)
		.build()
	);
for (int i=0; i<2; i++) {
	System.out.println(i==0 ? "Inputs:" : "Outputs:");
	PebbleStreamRuntime.SheetIoDescription[] descsSheet = i==0 ? descPbl.inputs : descPbl.outputs;
	for (int j=0; j<descsSheet.length; j++) {
		System.out.println(" " + descsSheet[j].name);
		for (int k=0; k<descsSheet[j].columns.length; k++) {
			System.out.printf("  ");
			for (int l=0; l<descsSheet[j].columns[k].headers.length; l++)
				System.out.print((l==0?"":" | ") + descsSheet[j].columns[k].headers[l]);
			System.out.printf("\n    ");
			Iterator<PebbleStreamRuntime.ColumnIoDescriptionType> types = descsSheet[j].columns[k].types.iterator();
			for (boolean first=true; types.hasNext(); first=false) System.out.print((first?"":", ")+types.next().toString());
			System.out.println();
		}
	}
}

getDependencies

Map<String,Set<String>> getDependencies(PebbleContext context)

PebbleContext options: pblId (required), pbl, reload

Returns a map from sheet name to the set of sheet names on which it depends.

Map<String,Set<String>> sheetToDependencies = PebbleStreamRuntime.getDependencies(new PebbleContext.Builder()
		.pbl("test.pbl")
		.pblId(42)
		.build()
	);
for (Map.Entry<String,Set<String>> entry: sheetToDependencies.entrySet()) {
	System.out.print(entry.getKey() + ": ");
	Iterator<String> deps = entry.getValue().iterator();
	for (boolean first=true; deps.hasNext(); first=false) System.out.print((first?"":", ")+deps.next());
	System.out.println();
}

getWorksheetHints

Map<String,Map<String,String[]>> getWorksheetHints(PebbleContext context)

PebbleContext options: pblId (required), pbl, reload

Returns a map of sheet name to hint name to an array of values, as created with the pebblestream:hint directive.

		Map<String,Map<String,String[]>> sheetToKeyToValues = PebbleStreamRuntime.getWorksheetHints(new PebbleContext.Builder()
				.pbl("test.pbl")
				.pblId(42)
				.build()
			);
		for (Map.Entry<String,Map<String,String[]>> entrySheet: sheetToKeyToValues.entrySet()) {
			System.out.println(entrySheet.getKey());
			for (Map.Entry<String,String[]> entryKey: entrySheet.getValue().entrySet()) {
				System.out.println(" " + entryKey.getKey());
				String[] values = entryKey.getValue();
				for (int i=0; i<values.length; i++) System.out.println("  "+values[i]);
			}
		}

loadPbl

void loadPbl(PebbleContext context)

PebbleContext options: pblId (required), pbl, reload

Loads the pebble into the cache, so future uses of it should be fast. This is done implicitly by runPbl if not done explicitly beforehand.

    PebbleStreamRuntime.loadPbl(new PebbleContext.Builder()
				.pbl("test.pbl")
				.pblId(42)
				.build()
			);

runPbl

Map<String,Object[][]> runPbl(PebbleContext context)

PebbleContext options: pblId (required), bigDecimal, bigDecimalPrecision, ignoreIsolatedWorksheets, inputColMap, inputCols, inputCsvStrings, inputRows, inputRowsOfStrings, outXlsxPath, outputWorksheets, pbl, postUrl, printClassifications, printDirectives, printInputs, printRender, reload, requireAllInputSheets, trimDirectives

Run the pebble and returns a map from output sheet name to rows of values.

Map<String,Object[][]> result = PebblestreamRuntime.runPbl(new PebbleContext.Builder()
		.pbl("test.pbl")
		.pblId(42)
		.bigDecimal(true)
		.build()
	);
for (Map.Entry<String,Object[][]> entry: result.entrySet()) {
	System.out.println(entry.getKey() + ":");
	Object[][] rows = entry.getValue();
	for (int i=0; i<rows.length; i++) {
		for (int j=0; j<rows[i].length; j++) System.out.print((j>0?" | ":"")+rows[i][j].toString());
		System.out.println();
	}
	System.out.println();
}

runPblReturnOutputContext

Object runPblReturnOutputContext(PebbleContext context)
Like runPbl, but returns an opaque object that can be passed to contextToRows or contextToColumns.

PebbleContext

The PebbleContext is how you pass options to the PebbleStreamRuntime functions. Some options will be required by the function (often pblId), and some will not be allowed for some functions. The documentation for the function will list which options it expects.

Here's an example of making a PebbleContext object:

import java.util.HashMap;
import java.util.Map;
import com.pebblestream.runtime.PebbleContext;

public class MakeContextExample {
	public PebbleContext makeContext() {
    Map<String,Object[][]> inputData = new HashMap<>();
    inputData.put(
      "Transactions",
      new Object[][] {
        {"Customer ID", "Amount"},
        {0, 42.23},
        {12, 1000},
        {8, -232.40}
      }
    );
    PebbleContext context = new PebbleContext.Builder()
      .pblId(42)
      .pbl("path/to/my/pebble.pbl")
      .bigDecimal(true)
      .inputRows(inputData)
      .build();
    return context;
  }
}

bigDecimal

bigDecimal(Boolean)
Use BigDecimal instead of double for decimal calculations.

bigDecimalPrecision

bigDecimalPrecision(Integer)
BigDecimal precision value.

ignoreIsolatedWorksheets

ignoreIsolatedWorksheets(Boolean)
Sheets without dependents or dependencies will be ignored.

inputColMap

inputColMap(Map<String,Map<Long,Object[]>>)
Map of sheet name to 0-index column to column values.

inputCols

inputCols(Map<String,Object[][]>)
Map of sheet name to columns.

inputCsvStrings

inputCsvStrings(Map<String,String>)
Map of sheet name to string of csv values representing the rows.

inputRows

inputRows(Map<String,Object[][]>)
Map of sheet name to rows of values.

inputRowsOfStrings

inputRowsOfStrings(Map<String,String[]>)
Map of sheet name to rows of strings which should be coerced to the appropriate type.

outXlsxPath

outXlsxPath(String)
File path to save results as an .xlsx file.

outputWorksheets

outputWorksheets(String[])
List of sheets to stitch together for the final output.

pbl

pbl(Object)
The bytes or path of the pebble to run.

pblId

pblId(Object)
The unique identifier for the executed pebble.

postUrl

postUrl(String)
A URL to POST the results to as JSON.

printClassifications

printClassifications(Boolean)
Print each sheet and its classification.

printDirectives

printDirectives(Boolean)
Print each directive (e.g., stop, sort).

printInputs

printInputs(String[])
Input sheets to print before rendering.

printRender

printRender(Boolean)
Print each worksheet and cell as the runtime renders it.

reload

reload(Boolean)
Don't check the cache for the pebble before loading and caching it.

requireAllInputSheets

requireAllInputSheets(Boolean)
If expected inputs are not provided, fail execution.

trimDirectives

trimDirectives(Boolean)
Removes stop and fail columns.

PblIoDescription

This is the object returned by describeInputsAndOutputs. Its two fields are SheetIoDescription[] inputs and SheetIoDescription[] outputs which each contain arrays of SheetIoDescription objects describing the types of the columns of the sheets. inputs contains the sheets which have no dependencies, and outputs those with no dependents (but some dependency).

SheetIoDescription

This is the object contained in arrays on the fields of PblIoDescription. It describes a worksheet and its columns. Its fields are String name (the name of the worksheet) and ColumnIoDescription[] columns (array of ColumnIoDescription objects representing the information of each column).

ColumnIoDescription

This is the object in the columns field of SheetIoDescription objects. It describes a column. Its fields are String[] headers (the list of headers in this column, usually 1) and Set<ColumnIoDescriptionType> types (a set of ColumnIoDescriptionType enums representing an excel value type).

ColumnIoDescriptionType

This is an enum contained in the types field of a ColumnIoDescription object. It has the following values:

  • BLANK a blank cell
  • BOOLEAN TRUE or FALSE
  • ERROR #REF!, #VALUE!, etc.
  • NUMBER a number, e.g. 42.1 or 0
  • TEXT a string of text, e.g. "hello"

RunPblError

This is the object returned by contextToError. Its fields are ErrorType error (an ErrorType enum), Address address (the cell Addresss where the error occurred), and Exception exception (the triggering exception, if any).

ErrorType

This is the enum contained in the error field on a RunPblError object. It has the following values:

  • UNKNOWN_KEYWORD an unknown error
  • NULL #NULL! in Excel
  • DIV0 #DIV/0! in Excel
  • VALUE #VALUE! in Excel
  • REF #REF! in Excel
  • NAME #NAME? in Excel
  • NUM #NUM! in Excel
  • NA #N/A in Excel
  • STOP_COLUMN_TIME_TRAVEL A column with a stop directive attempted to reference a later row
  • TOO_LONG_WITHOUT_HALT A stop column ran for too long without stopping
  • CIRCULAR_DEPENDENCY A cell referred back to itself
  • NOT_BLANK_COLUMN A column with a not-blank directive was blank
  • FAIL_COLUMN A column with a fail directive was true
  • UNKNOWN_TYPE an unknown error

Address

This object represents an address to a cell in a spreadsheet. Its fields are String sheet, long column (zero-indexed), and long row (zero-indexed).

Updated over 1 year ago