### Instantiate Diffy with Default JsonUtil

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/05-diffy.md

Creates a Diffy instance using the default JsonUtil for cloning operations. This is the simplest way to get started with Diffy.

```java
Diffy diffy = new Diffy();
```

--------------------------------

### Jolt Chainr Spec File Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

An example of a Jolt Chainr specification file, defining a sequence of transformation operations.

```json
[
    {
        "operation": "shift",
        "spec": {
            "rating": {
                "value": "Rating"
            }
        }
    },
    {
        "operation": "default",
        "spec": {
            "Status": "active"
        }
    },
    {
        "operation": "sort"
    }
]
```

--------------------------------

### Build Chainr with Custom Instantiator (Guice Example)

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/06-chainr-builder.md

Demonstrates using a custom instantiator, specifically a Guice-based one, to hydrate Jolt transforms with their dependencies.

```java
import com.bazaarvoice.jolt.chainr.ChainrBuilder;
import com.bazaarvoice.jolt.chainr.ChainrEntry;
import com.bazaarvoice.jolt.chainr.instantiator.ChainrInstantiator;
import com.google.inject.Injector;

public class GuiceChainrInstantiator implements ChainrInstantiator {
    private final Injector injector;
    
    public GuiceChainrInstantiator(Injector injector) {
        this.injector = injector;
    }
    
    @Override
    public JoltTransform hydrateTransform(ChainrEntry entry) {
        // Use Guice to instantiate transforms with dependencies
        return injector.getInstance(/* ... */);
    }
}

// Usage
Injector injector = /* Guice injector setup */;
Chainr chainr = new ChainrBuilder(spec)
    .loader(new GuiceChainrInstantiator(injector))
    .build();
```

--------------------------------

### Chainr Constructor Usage Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Demonstrates how to create a Chainr instance by providing a list of JoltTransforms, such as Shiftr and Sortr, to be executed in sequence.

```java
import com.bazaarvoice.jolt.Chainr;
import com.bazaarvoice.jolt.Shiftr;
import com.bazaarvoice.jolt.Sortr;
import java.util.Arrays;
import java.util.List;

Map<String, Object> shiftrSpec = /* spec */;
Shiftr shiftr = new Shiftr(shiftrSpec);
Sortr sortr = new Sortr();

Chainr chainr = new Chainr(Arrays.asList(shiftr, sortr));
Object result = chainr.transform(input);
```

--------------------------------

### Sort Order Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Demonstrates the specific sorting order applied by the 'jolt sort' command, where '~' prefixed keys appear first, followed by other keys alphabetically.

```json
{
  "zulu": 1,
  "alpha": 2,
  "~meta": "info",
  "bravo": 3
}
```

```json
{
  "~meta" : "info",
  "alpha" : 2,
  "bravo" : 3,
  "zulu" : 1
}
```

--------------------------------

### Full Chainr Spec Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

An example of a Jolt Chainr specification, which executes multiple transforms in a defined sequence.

```json
[
  {
    "operation": "cardinality",
    "spec": {"photos": "MANY"}
  },
  {
    "operation": "shift",
    "spec": {"photos": {"[*]": {"url": "images[&1]"}}}
  },
  {
    "operation": "default",
    "spec": {"status": "active"}
  },
  {
    "operation": "remove",
    "spec": {"internal": ""}
  },
  {
    "operation": "sort"
  }
]
```

--------------------------------

### Using the Transform Interface

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/01-core-interfaces.md

Example of instantiating and using a stateless Jolt transform like Sortr. Ensure the input is a hydrated Jackson Map.

```Java
import com.bazaarvoice.jolt.Sortr;
import com.bazaarvoice.jolt.Transform;
import java.util.Map;

// Create a transform instance
Transform sorter = new Sortr();

// Apply the transform
Map<String, Object> input = /* hydrated JSON Map */;
Object output = sorter.transform(input);
```

--------------------------------

### Jolt Command-Line Interface Examples

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/README.md

These bash commands demonstrate common Jolt operations: transforming JSON files, diffing JSON files, sorting JSON, and piping data through Jolt transforms.

```bash
# Transform JSON file
jolt transform spec.json input.json
```

```bash
# Compare two JSON files
jolt diffy expected.json actual.json
```

```bash
# Sort JSON alphabetically
jolt sort unsorted.json
```

```bash
# Pipeline example
curl -s "https://api.example.com/data" | \
    jolt transform spec.json | \
    jolt diffy expected.json -i
```

--------------------------------

### Example Implementation of SpecDriven Transform

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/01-core-interfaces.md

Demonstrates how to implement the SpecDriven interface for a custom Jolt Transform. Ensure the constructor is annotated with @Inject and handles spec validation.

```java
// This is how SpecDriven transforms are instantiated by Chainr
import com.bazaarvoice.jolt.SpecDriven;
import com.bazaarvoice.jolt.Transform;
import javax.inject.Inject;

public class MyCustomTransform implements SpecDriven, Transform {
    
    private Object spec;
    
    @Inject
    public MyCustomTransform(Object spec) {
        if (spec == null) {
            throw new SpecException("MyCustomTransform requires a spec");
        }
        this.spec = spec;
    }
    
    @Override
    public Object transform(Object input) {
        // Implementation using this.spec
        return input;
    }
}
```

--------------------------------

### Usage Example for ContextualTransform

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/01-core-interfaces.md

Demonstrates how to create a context map and use it with a ContextualTransform implementation to transform input JSON. The context map can provide external data to influence the transformation.

```java
import com.bazaarvoice.jolt.ContextualTransform;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> context = new HashMap<>();
context.put("protocol", "https");
context.put("domain", "example.com");

// Apply transform with context
Object input = /* hydrated JSON */;
ContextualTransform transform = /* implementation */;
Object output = transform.transform(input, context);
```

--------------------------------

### Jolt Java Transformation Example

Source: https://github.com/bazaarvoice/jolt/blob/master/gettingStarted.md

A sample Java class demonstrating how to load a Jolt specification and input JSON from the classpath, perform a transformation, and print the output. This requires the Jolt artifacts to be on your classpath.

```java
package com.bazaarvoice.jolt.sample;

import com.bazaarvoice.jolt.Chainr;
import com.bazaarvoice.jolt.JsonUtils;

import java.io.IOException;
import java.util.List;

public class JoltSample {

    public static void main(String[] args) throws IOException {

        // How to access the test artifacts, i.e. JSON files
        //  JsonUtils.classpathToList : assumes you put the test artifacts in your class path
        //  JsonUtils.filepathToList : you can use an absolute path to specify the files

        List chainrSpecJSON = JsonUtils.classpathToList( "/json/sample/spec.json" );
        Chainr chainr = Chainr.fromSpec( chainrSpecJSON );

        Object inputJSON = JsonUtils.classpathToObject( "/json/sample/input.json" );

        Object transformedOutput = chainr.transform( inputJSON );
        System.out.println( JsonUtils.toJsonString( transformedOutput ) );
    }
}
```

--------------------------------

### Removr Usage Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Demonstrates how to use the Removr transform to remove sensitive data like SSN from a JSON input. Ensure Jolt and its dependencies are included in your project.

```java
import com.bazaarvoice.jolt.Removr;
import com.bazaarvoice.jolt.JsonUtils;

// Input with sensitive data
String inputJson = "{"
    + "\"user\": {\"name\": \"Alice\", \"ssn\": \"123-45-6789\", \"status\": \"active\"}"
    + "}";

// Removr spec - remove SSN
Map<String, Object> spec = JsonUtils.javason("{"
    + "'user': {'ssn': ''}"
    + "}");

Removr removr = new Removr(spec);
Object input = JsonUtils.jsonToObject(inputJson);
Object output = removr.transform(input);

// Output: {"user": {"name": "Alice", "status": "active"}}
```

--------------------------------

### Integrate Jolt Transformation into CI/CD Pipelines

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This example shows how to use Jolt CLI within a CI/CD pipeline to automatically verify that transformed JSON output matches expected results. It exits with an error code if the diffy command fails.

```bash
# In CI/CD pipeline
jolt transform spec.json input.json | jolt diffy expected.json -i
if [ $? -eq 0 ]; then
    echo "Transform output matches expected"
else
    echo "Transform output differs from expected"
    exit 1
fi
```

--------------------------------

### Shiftr Spec Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

Defines how to transform JSON structure by mapping input paths to output paths.

```json
{
  "input.path": "output.path",
  "nested": {
    "data": "destination.location"
  },
  "*": {
    "value": "templated.&1.value"
  }
}
```

--------------------------------

### Usage Example: Convert name to uppercase

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Demonstrates using the Overwritr transformer to convert a 'name' field to uppercase using the '#toUpper' stock function.

```java
import com.bazaarvoice.jolt.Modifier;
import com.bazaarvoice.jolt.JsonUtils;

String inputJson = "{\"name\": \"alice\"}";

// Convert name to uppercase
Map<String, Object> spec = JsonUtils.javason("{"
    + "'name': {'#toUpper': '@(1,name)'}"
    + "}");

Modifier.Overwritr overwritr = new Modifier.Overwritr(spec);
Object input = JsonUtils.jsonToObject(inputJson);
Object output = overwritr.transform(input, null);

// Output: {"name": "ALICE"}
```

--------------------------------

### Sortr Usage Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Demonstrates how to use the Sortr class to sort a JSON string. The output keys are ordered alphabetically, with '~' prefixed keys appearing first.

```java
import com.bazaarvoice.jolt.Sortr;
import com.bazaarvoice.jolt.JsonUtils;

String unsortedJson = "{"
    + "\"zebra\": 1, "
    + "\"apple\": 2, "
    + "\"~meta\": \"info\""
    + "}";

Sortr sortr = new Sortr();
Object input = JsonUtils.jsonToObject(unsortedJson);
Object sorted = sortr.transform(input);

// Output keys are ordered: ~meta, apple, zebra
String output = JsonUtils.toPrettyJsonString(sorted);
System.out.println(output);
```

--------------------------------

### Handle Comparing Non-Existent Files with Jolt CLI

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This example illustrates the error message when the `jolt diffy` command is used with a file that does not exist. The CLI will report the missing file and exit with code 1.

```bash
$ jolt diffy file1.json file2.json
ERROR: Cannot find file: file1.json
```

--------------------------------

### Shiftr Usage Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Demonstrates how to use the Shiftr transform to reposition data from an input JSON to an output JSON based on a defined spec. Ensure Jolt and JsonUtils are imported.

```java
import com.bazaarvoice.jolt.Shiftr;
import com.bazaarvoice.jolt.JsonUtils;

// Input JSON
String inputJson = "{"
    + "\"rating\": {\"primary\": {\"value\": 3, \"max\": 5}}"
    + "}";

// Shiftr spec
Map<String, Object> spec = JsonUtils.javason("{"
    + "'rating': {'primary': {'value': 'Rating', 'max': 'RatingRange'}}"
    + "}");

Shiftr shiftr = new Shiftr(spec);
Object input = JsonUtils.jsonToObject(inputJson);
Object output = shiftr.transform(input);

// Output: {"Rating": 3, "RatingRange": 5}
```

--------------------------------

### Build Basic Chainr Instance

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/06-chainr-builder.md

Construct a basic Chainr instance from a JSON spec loaded from the classpath. This is the simplest way to get a functional Chainr object.

```java
import com.bazaarvoice.jolt.Chainr;
import com.bazaarvoice.jolt.chainr.ChainrBuilder;
import com.bazaarvoice.jolt.JsonUtils;

// Load spec from classpath
List<Object> chainrSpec = JsonUtils.classpathToList("/chainr/myChainr.json");

// Build chainr
Chainr chainr = new ChainrBuilder(chainrSpec).build();

// Use it
Object input = JsonUtils.jsonToMap("{\"rating\": 5}");
Object output = chainr.transform(input);
```

--------------------------------

### Type Mismatch Comparison in Java

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/05-diffy.md

This example illustrates how Diffy handles type mismatches between expected and actual values. When types differ, the entire subtree is retained as a difference.

```java
Object expected = JsonUtils.jsonToMap("{\"count\": 5}");
Object actual = JsonUtils.jsonToMap("{\"count\": \"5\"}");

Diffy.Result result = diffy.diff(expected, actual);
// result.expected = {"count": 5}
// result.actual = {"count": "5"}
// Entire values retained due to type mismatch
```

--------------------------------

### Removr Spec DSL Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

This JSON structure defines the paths to be removed from the input data. Any value in the spec indicates the corresponding path should be removed.

```json
{
  "privateKey": "",
  "nested": {
    "secret": ""
  },
  "items": {
    "[*]": {
      "internalId": ""
    }
  }
}
```

--------------------------------

### Validate, Transform, and Verify JSON with Jolt CLI

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This snippet demonstrates a typical validation pipeline using Jolt CLI. It checks input validity, performs transformation, and verifies the output against an expected file. Ensure Jolt is installed and accessible in your PATH.

```bash
# Check if input is valid JSON
jolt sort input.json > /dev/null || exit 1

# Transform
jolt transform spec.json input.json > output.json || exit 1

# Verify against expected
jolt diffy expected.json output.json > /dev/null || exit 1

echo "Transformation successful!"
```

--------------------------------

### Handle Jolt Transform Errors

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This example shows the expected output and exit code when the Jolt transform command is executed with an invalid specification. The CLI will report an error and exit with code 1.

```bash
$ jolt transform invalid-spec.json input.json
ERROR: Invalid spec provided
[error details]
```

--------------------------------

### Apply Default Values to JSON

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Example of using Defaultr to apply default values to a JSON input. The output includes original values where present and defaults for missing fields like 'category' and 'tags'.

```java
import com.bazaarvoice.jolt.Defaultr;
import com.bazaarvoice.jolt.JsonUtils;

// Input (missing some fields)
String inputJson = "{\"rating\": 3, \"status\": \"active\"}";

// Default spec
Map<String, Object> spec = JsonUtils.javason("{"
    + "'rating': 5, "
    + "'status': 'pending', "
    + "'category': 'general', "
    + "'tags': []"
    + "}");

Defaultr defaultr = new Defaultr(spec);
Object input = JsonUtils.jsonToObject(inputJson);
Object output = defaultr.transform(input);

// Output includes original rating (3) but gets category and tags defaults
```

--------------------------------

### Handle File Not Found Errors with Jolt CLI

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This example demonstrates the error message and exit code when Jolt CLI attempts to process a file that does not exist. The CLI will report the missing file and exit with code 1.

```bash
$ jolt transform missing.json input.json
ERROR: Cannot find file: missing.json
```

--------------------------------

### Execute Transforms From Start Index to End

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Use this to execute transforms within a specific range, defined by inclusive start and exclusive end indices. This is useful for testing specific segments of a transform chain. Ensure 'from' is non-negative and 'to' is within bounds and greater than 'from'.

```java
// Skip the first 2 transforms
Object skipFirst = chainr.transform(2, chainr.getContextualTransforms().size(), input);
```

--------------------------------

### Get Default JsonUtil Instance

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/04-json-utilities.md

Retrieve the default, pre-configured JsonUtil instance for standard JSON operations.

```java
JsonUtil defaultUtil = JsonUtils.getDefaultJsonUtil();
```

--------------------------------

### CardinalityTransform Spec Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

Specifies the cardinality (ONE or MANY) for fields, used to normalize single values into arrays or vice-versa.

```json
{
  "tags": "MANY",
  "primary": "ONE",
  "items": "MANY"
}
```

--------------------------------

### Removr Spec Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

Defines fields to be removed from a JSON object. Used for sanitizing data or removing sensitive information.

```json
{
  "internalId": "",
  "nested": {
    "secret": ""
  },
  "items": {
    "[*]": {
      "temp": ""
    }
  }
}
```

--------------------------------

### Defaultr Spec Example

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

Specifies default values for fields in a JSON object. Useful for ensuring consistent data structures.

```json
{
  "status": "active",
  "tags": [],
  "createdAt": "2024-01-01"
}
```

--------------------------------

### Chaining Curl, Jolt Transform, and Sort

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Shows how to fetch data using curl, transform it with Jolt, and then sort the result.

```bash
curl -s https://api.example.com/data | jolt transform spec.json | jolt sort
```

--------------------------------

### Initialize and Reuse Chainr Across Threads

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Demonstrates how to initialize a Chainr instance once and then reuse it across multiple threads for parallel data transformation. Ensure all transforms in the chain are stateless.

```java
Chainr chainr = Chainr.fromSpec(spec);

ExecutorService executor = Executors.newFixedThreadPool(10);
for (int i = 0; i < 100; i++) {
    final Object inputData = getInputData(i);
    executor.submit(() -> {
        Object result = chainr.transform(inputData);
        processResult(result);
    });
}
```

--------------------------------

### Provide Runtime Configuration with Context

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/08-usage-patterns.md

Use a HashMap to pass runtime parameters like base URLs or API versions to Jolt transformations. This is essential for ContextualTransforms that adapt their behavior based on external configurations.

```java
import java.util.HashMap;
import java.util.Map;

Object input = JsonUtils.jsonToMap(inputJson);

// Build context map with runtime parameters
Map<String, Object> context = new HashMap<>();
context.put("baseUrl", "https://api.example.com");
context.put("apiVersion", "v2");
context.put("environment", "production");

// Apply chainr with context (for ContextualTransforms)
Object output = chainr.transform(input, context);
```

--------------------------------

### Create a Jolt Transform Spec

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/00-START-HERE.md

Define a JSON specification for Jolt transformations. This example uses 'shift' to reposition data and 'default' to add a default value.

```json
[
    {
        "operation": "shift",
        "spec": {
            "user": {
                "firstName": "name.first",
                "lastName": "name.last"
            }
        }
    },
    {
        "operation": "default",
        "spec": {
            "status": "active"
        }
    }
]
```

--------------------------------

### Jolt CLI with grep

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Uses grep to find matching transformed outputs from the Jolt CLI.

```bash
# Find matching transformed outputs
jolt transform spec.json input.json | grep -o '"field":"[^" ]*"'
```

--------------------------------

### Jolt CLI General Usage

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

The basic structure for invoking any Jolt CLI subcommand.

```bash
jolt <subcommand> [options] <arguments>
```

--------------------------------

### Jolt CLI with sed

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Uses sed to perform replacements on the output of the Jolt CLI transformation.

```bash
# Replace in transform output
jolt transform spec.json input.json | sed 's/old/new/g'
```

--------------------------------

### Jolt Package Structure

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/README.md

Overview of the Jolt library's package organization.

```tree
jolt-core/
├── Chainr, Transform, ContextualTransform, SpecDriven
├── Stock transforms (Shiftr, Defaultr, Removr, Sortr, CardinalityTransform, Modifier)
├── Exceptions (JoltException, SpecException, TransformException)
└── Internal implementation

json-utils/
├── JsonUtils, JsonUtil
├── Diffy, ArrayOrderObliviousDiffy
└── JSON exceptions

chainr/
├── ChainrBuilder, ChainrInstantiator
└── Spec parsing

cli/
└── Command-line interface (bin/jolt script)
```

--------------------------------

### Jolt CLI - Batch Operations Comparison

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Compares inefficient batch operations using multiple Jolt CLI invocations with a more efficient single invocation per file group.

```bash
# Slow - 100 separate invocations
for file in *.json; do
    jolt transform spec.json "$file"
done
```

```bash
# Better - single invocation per file group if possible
```

--------------------------------

### Get Contextual Transforms from Chainr

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Retrieve an unmodifiable list of all `ContextualTransform` instances present in the Chainr using `getContextualTransforms()`. This helps in inspecting the chain's contextual capabilities.

```java
List<ContextualTransform> contextualTransforms = chainr.getContextualTransforms();
System.out.println("Chain contains " + contextualTransforms.size() + " contextual transforms");
```

--------------------------------

### Chainr Static Methods

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

Static methods for creating and initializing Chainr instances.

```APIDOC
## Chainr Static Methods

### `fromSpec(Object input)`

#### Description
Creates a Chainr instance from a provided specification object.

#### Parameters
* **input** (Object) - Required - The specification object to create the Chainr from.

#### Returns
* Chainr - A new Chainr instance.

### `fromSpec(Object, ChainrInstantiator)`

#### Description
Creates a Chainr instance with a custom instantiator.

#### Parameters
* **input** (Object) - Required - The specification object.
* **instantiator** (ChainrInstantiator) - Required - A custom instantiator for Chainr.

#### Returns
* Chainr - A new Chainr instance with the custom instantiator.
```

--------------------------------

### Nested Structure Difference in Java

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/05-diffy.md

This example demonstrates Diffy's ability to compare nested JSON objects and pinpoint differences within them. It highlights specific fields that have changed.

```java
Map<String, Object> expected = JsonUtils.jsonToMap(
    "{\"user\": {\"profile\": {\"age\": 30, \"city\": \"NYC\"}}}"
);

Map<String, Object> actual = JsonUtils.jsonToMap(
    "{\"user\": {\"profile\": {\"age\": 31, \"city\": \"NYC\"}}}"
);

Diffy.Result result = diffy.diff(expected, actual);
// Only the "age" field differs
```

--------------------------------

### Pre-compile Chainrs at Startup

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/08-usage-patterns.md

Load and cache Jolt Chainrs during application startup to avoid repeated parsing and compilation overhead during runtime. This is useful for frequently used transformations.

```java
public class TransformRegistry {
    private static final Map<String, Chainr> TRANSFORMS = new HashMap<>();
    
    static {
        // Load all specs at startup
        TRANSFORMS.put("es-to-api", loadChainr("/chainr/es-to-api.json"));
        TRANSFORMS.put("db-to-cache", loadChainr("/chainr/db-to-cache.json"));
        TRANSFORMS.put("normalize", loadChainr("/chainr/normalize.json"));
    }
    
    private static Chainr loadChainr(String path) {
        try {
            List<Object> spec = JsonUtils.classpathToList(path);
            return Chainr.fromSpec(spec);
        } catch (Exception e) {
            throw new ExceptionInInitializerError(e);
        }
    }
    
    public static Chainr get(String name) {
        Chainr chainr = TRANSFORMS.get(name);
        if (chainr == null) {
            throw new IllegalArgumentException("Unknown transform: " + name);
        }
        return chainr;
    }
}

// Usage
Object result = TransformRegistry.get("es-to-api").transform(input);
```

--------------------------------

### Handling Invalid Specification Errors

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/07-exceptions.md

Illustrates catching a SpecException, which is thrown when the Jolt specification is malformed or invalid. This example shows how to handle errors related to an invalid Chainr spec structure.

```java
import com.bazaarvoice.jolt.exception.SpecException;

try {
    // Spec with no "operation" field
    List<Object> badSpec = JsonUtils.jsonToList(
        "[{"spec": {}}]"
    );
    Chainr chainr = Chainr.fromSpec(badSpec);
} catch (SpecException e) {
    System.err.println("Invalid spec: " + e.getMessage());
}
```

--------------------------------

### Basic JSON Transform (Java)

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/00-START-HERE.md

Load a Jolt specification, create a Chainr instance, and transform input JSON. Ensure the spec JSON is available on the classpath.

```java
import com.bazaarvoice.jolt.Chainr;
import com.bazaarvoice.jolt.JsonUtils;

// Load spec
List<Object> spec = JsonUtils.classpathToList("/chainr/spec.json");

// Create chainr
Chainr chainr = Chainr.fromSpec(spec);

// Transform
Object input = JsonUtils.jsonToMap(inputJson);
Object output = chainr.transform(input);
```

--------------------------------

### Java Integration - Jolt CLI Transformation

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

A Java class demonstrating how to invoke the Jolt CLI for JSON transformations. It manages temporary files for input and reads the output stream.

```java
import java.io.*;

public class JoltCLI {
    public static Object transform(Object input, String specPath) 
            throws IOException {
        // Write input to temp file
        File tempInput = File.createTempFile("jolt", ".json");
        JsonUtils.toFile(input, tempInput);
        
        // Run CLI
        ProcessBuilder pb = new ProcessBuilder(
            "jolt", "transform", specPath, tempInput.getAbsolutePath()
        );
        Process p = pb.start();
        
        // Read output
        BufferedReader reader = new BufferedReader(
            new InputStreamReader(p.getInputStream())
        );
        StringBuilder output = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            output.append(line);
        }
        
        tempInput.delete();
        return JsonUtils.jsonToObject(output.toString());
    }
}
```

--------------------------------

### Chaining Jolt Transform with jq Filter

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Illustrates transforming JSON with Jolt and then filtering the output using jq.

```bash
jolt transform spec.json input.json | jq '.items[]'
```

--------------------------------

### Jolt Chainr Specification with Custom Transform

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Example of a Jolt Chainr specification that includes a custom transform operation. Use the fully qualified class name for the 'operation' field and provide its specific 'spec'.

```json
[
    {
        "operation": "com.example.MyCustomTransform",
        "spec": {
            "customParam": "value"
        }
    }
]
```

--------------------------------

### File-Based Methods

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/04-json-utilities.md

Methods for loading and parsing JSON from files on the filesystem.

```APIDOC
## filepathToObject(String filePath)

### Description
Load and parse JSON from a specified filesystem path.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
Object config = JsonUtils.filepathToObject("/etc/config.json");
```

### Response
#### Success Response
- **config** (Object) - Parsed JSON

#### Response Example
N/A
```

```APIDOC
## filepathToMap(String filePath)

### Description
Load a JSON file from the filesystem and parse it directly into a Map.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
Map<String, Object> spec = JsonUtils.filepathToMap("/specs/shiftr.json");
```

### Response
#### Success Response
- **spec** (Map<String, Object>) - Parsed Map

#### Response Example
N/A
```

```APIDOC
## filepathToList(String filePath)

### Description
Load a JSON file from the filesystem and parse it directly into a List.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
// Example usage not provided in source
```

### Response
#### Success Response
- **list** (List<Object>) - Parsed List

#### Response Example
N/A
```

--------------------------------

### Diffy(JsonUtil jsonUtil) Constructor

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/05-diffy.md

Creates a Diffy instance with a custom JsonUtil for cloning operations.

```APIDOC
## Diffy(JsonUtil jsonUtil)

### Description
Creates a Diffy with a custom JsonUtil for cloning operations.

### Method
```java
public Diffy(JsonUtil jsonUtil)
```

### Parameters
#### Path Parameters
- **jsonUtil** (JsonUtil) - Required - Custom JsonUtil instance for cloning

### Example
```java
import com.bazaarvoice.jolt.JsonUtils;
import com.bazaarvoice.jolt.Diffy;

JsonUtil customUtil = JsonUtils.customJsonUtil(/* ObjectMapper */);
Diffy diffy = new Diffy(customUtil);
```
```

--------------------------------

### transform(int from, int to, Object input)

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Executes a specific segment of the transformation chain, defined by a start index (inclusive) and an end index (exclusive). This method is suitable for isolating and testing a range of transforms.

```APIDOC
## transform(int from, int to, Object input)

### Description
Execute transforms from the specified start index to the specified end index.

### Method
Not specified (assumed to be a method call in Java)

### Parameters
- **from** (int) - Required - Start index (inclusive), 0-based
- **to** (int) - Required - End index (exclusive)
- **input** (Object) - Required - Input to transform

### Returns
`Object` — Result of executing transforms [from, to)

### Throws
`TransformException` if execution fails
`TransformException` if from < 0 or to > transforms.size() or to <= from
```

--------------------------------

### Handle Invalid JSON Input Errors with Jolt CLI

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This example shows the error output when Jolt CLI receives invalid JSON as input. The CLI will report a JSON parsing error and exit with code 1.

```bash
$ echo '{invalid json}' | jolt transform spec.json
ERROR: Invalid JSON input
[parse error details]
```

--------------------------------

### Defaultr Constructor

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Initializes Defaultr with a specification for default values. The spec is a Map describing the defaults to apply. Throws SpecException if the spec is invalid.

```java
public Defaultr(Object spec);
```

--------------------------------

### Unit Test Jolt Transforms

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/08-usage-patterns.md

Demonstrates how to unit test Jolt transforms using JUnit. Load input, expected output, and spec files from the classpath, execute the transform, and assert the output using Diffy.

```java
import org.junit.Test;
import static org.junit.Assert.*;

public class ChainrTest {
    
    @Test
    public void testRatingTransform() throws Exception {
        // Load test data
        Object input = JsonUtils.classpathToObject("/test/input.json");
        Object expected = JsonUtils.classpathToObject("/test/expected.json");
        
        // Load and execute transform
        List<Object> spec = JsonUtils.classpathToList("/test/spec.json");
        Chainr chainr = Chainr.fromSpec(spec);
        Object actual = chainr.transform(input);
        
        // Verify
        Diffy diffy = new Diffy();
        Diffy.Result diff = diffy.diff(expected, actual);
        
        assertTrue("Transform output matches expected", diff.isEmpty());
    }
    
    @Test
    public void testPartialChain() {
        Object input = JsonUtils.javason(
            "{'rating': {'value': 5, 'max': 10}}"
        );
        
        List<Object> spec = JsonUtils.classpathToList("/spec.json");
        Chainr chainr = Chainr.fromSpec(spec);
        
        // Test first 2 operations only
        Object intermediate = chainr.transform(0, 2, input);
        
        assertTrue(intermediate instanceof Map);
    }
}
```

--------------------------------

### transform(int from, int to, Object input, Map<String, Object> context)

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Executes a segment of the transformation chain between specified start and end indices (inclusive and exclusive, respectively), utilizing a provided context map. This offers granular control over chain execution with contextual data.

```APIDOC
## transform(int from, int to, Object input, Map<String, Object> context)

### Description
Execute a partial chain from start to end index with context.

### Method
Not specified (assumed to be a method call in Java)

### Parameters
- **from** (int) - Required - Start index (inclusive)
- **to** (int) - Required - End index (exclusive)
- **input** (Object) - Required - Input to transform
- **context** (Map<String, Object>) - Optional - Context map

### Returns
`Object` — Result of partial chain execution
```

--------------------------------

### Process API Data with Jolt CLI

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This script fetches raw data from an API, transforms it using a Jolt specification, and then posts the transformed data to another API endpoint. It uses `curl` for HTTP requests and pipes the output between commands.

```bash
#!/bin/bash

# Fetch data from API, transform, and post result
curl -s "https://api.example.com/raw-data" | \
    jolt transform api-spec.json | \
    curl -X POST \
         -H "Content-Type: application/json" \
         -d @- \
         https://other-api.com/ingest
```

--------------------------------

### Jolt CLI with jq - Pre-filtering

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Integrates Jolt CLI with jq for filtering JSON data before applying the Jolt transformation.

```bash
# Use jq for filtering before transform
jq '.important_fields' input.json | jolt transform spec.json
```

--------------------------------

### Diffy() Constructor

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/05-diffy.md

Creates a Diffy instance using the default JsonUtil for cloning operations.

```APIDOC
## Diffy()

### Description
Creates a Diffy using the default JsonUtil for cloning.

### Method
```java
public Diffy()
```

### Example
```java
Diffy diffy = new Diffy();
```
```

--------------------------------

### JsonUtils Static Methods

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/INDEX.md

Utility methods for converting between JSON strings, objects, and files.

```APIDOC
## JsonUtils Static Methods

### String→Object Conversion

*   `jsonToObject(String jsonString)`: Converts a JSON string to an Object.
*   `jsonToMap(String jsonString)`: Converts a JSON string to a Map.
*   `jsonToList(String jsonString)`: Converts a JSON string to a List.

### File→Object Conversion

*   `filepathToObject(String filepath)`: Reads a file and converts its JSON content to an Object.
*   `filepathToMap(String filepath)`: Reads a file and converts its JSON content to a Map.
*   `filepathToList(String filepath)`: Reads a file and converts its JSON content to a List.

### Classpath→Object Conversion

*   `classpathToObject(String resourcePath)`: Reads a resource from the classpath and converts its JSON content to an Object.
*   `classpathToMap(String resourcePath)`: Reads a resource from the classpath and converts its JSON content to a Map.
*   `classpathToList(String resourcePath)`: Reads a resource from the classpath and converts its JSON content to a List.
*   `classpathToType(String resourcePath, Class<?> type)`: Reads a resource from the classpath and converts its JSON content to a specified type.

### Stream→Object Conversion

*   `jsonToObject(InputStream inputStream)`: Converts JSON content from an InputStream to an Object.
*   `jsonToList(InputStream inputStream)`: Converts JSON content from an InputStream to a List.

### Type Conversion

*   `stringToType(String value, Class<?> type)`: Converts a string value to a specified type.
*   `fileToType(String filepath, Class<?> type)`: Reads a file and converts its content to a specified type.
*   `streamToType(InputStream inputStream, Class<?> type)`: Reads from an InputStream and converts its content to a specified type.

### Object→String Conversion

*   `toJsonString(Object object)`: Converts an object to its JSON string representation.
*   `toPrettyJsonString(Object object)`: Converts an object to a pretty-printed JSON string.

### Utilities

*   `cloneJson(Object object)`: Creates a deep clone of a JSON object.
*   `javason(Object object)`: Converts an object to a Javason representation.
*   `customJsonUtil(Object object, JsonUtil customUtil)`: Uses a custom JsonUtil for JSON operations.
*   `getDefaultJsonUtil()`: Retrieves the default JsonUtil instance.
```

--------------------------------

### Chaining Jolt Transform with Sort

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

Demonstrates piping the output of a Jolt transform to the Jolt sort command for ordered JSON output.

```bash
jolt transform spec.json input.json | jolt sort
```

--------------------------------

### Basic JSON Transform (CLI)

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/00-START-HERE.md

Perform JSON transformations using the Jolt CLI. You can pipe output from one command to another, such as for sorting.

```bash
jolt transform spec.json input.json
jolt transform spec.json input.json | jolt sort
curl -s api.example.com/data | jolt transform spec.json
```

--------------------------------

### Chainr.fromSpec(Object input, ChainrInstantiator instantiator)

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/02-chainr.md

Creates a Chainr using a custom instantiator for loading transforms. This allows for more control over how transform instances are created, which can be useful for dependency injection or custom transform loading logic.

```APIDOC
## Chainr.fromSpec(Object input, ChainrInstantiator instantiator)

### Description
Creates a Chainr using a custom instantiator for loading transforms. This allows for more control over how transform instances are created, which can be useful for dependency injection or custom transform loading logic.

### Method
Static Factory Method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **input** (Object) - Required - Chainr specification
* **instantiator** (ChainrInstantiator) - Required - Custom instantiator for creating transform instances

### Response
#### Success Response
* **Chainr** - A configured Chainr instance

#### Error Response
None explicitly mentioned
```

--------------------------------

### Definr Constructor

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Initializes the Definr transformer with a specification. An optional map of custom functions can be provided. Definr only writes if the key/index is missing.

```java
@Inject
public Definr(Object spec);
```

```java
public Definr(Object spec, Map<String, Function> functionsMap);
```

--------------------------------

### CardinalityTransform Constructor

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Initializes CardinalityTransform with a specification map. The spec defines the desired cardinality for each path. Throws SpecException if the spec is invalid.

```java
import com.bazaarvoice.jolt.CardinalityTransform;
import com.bazaarvoice.jolt.JsonUtils;

// Input sometimes has photos as single object, sometimes as array
String inputJson = "{\"photos\": {\"url\": \"photo.jpg\"}}";

// Ensure photos is always an array
Map<String, Object> spec = JsonUtils.javason("{"
    + "'photos': 'MANY'" 
    + "}");

CardinalityTransform card = new CardinalityTransform(spec);
Object input = JsonUtils.jsonToObject(inputJson);
Object output = card.transform(input);

// Output: {"photos": [{"url": "photo.jpg"}]}
```

--------------------------------

### Chaining Stock Transforms

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/03-stock-transforms.md

Demonstrates a common pattern of chaining multiple stock transforms (cardinality, shift, default, remove, sort) to process and reshape JSON data.

```json
[
    {
        "operation": "cardinality",
        "spec": {
            "items": "MANY",
            "tags": "MANY"
        }
    },
    {
        "operation": "shift",
        "spec": {
            "items": {
                "[*]": {
                    "id": "products[&1].id",
                    "name": "products[&1].title"
                }
            }
        }
    },
    {
        "operation": "default",
        "spec": {
            "status": "pending",
            "createdAt": "2024-01-01"
        }
    },
    {
        "operation": "remove",
        "spec": {
            "internalMetadata": ""
        }
    },
    {
        "operation": "sort"
    }
]
```

--------------------------------

### Chainr Construction Methods

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/06-chainr-builder.md

Use static factory methods for simple Chainr construction or the builder for full control over instantiation, including custom loaders and classloaders.

```java
Chainr chainr = Chainr.fromSpec(spec);
```

```java
Chainr chainr = Chainr.fromSpec(spec, customInstantiator);
```

```java
Chainr chainr = new ChainrBuilder(spec)
    .loader(customInstantiator)
    .withClassLoader(classLoader)
    .build();
```

--------------------------------

### Initialize ChainrBuilder with Spec

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/06-chainr-builder.md

Initialize a ChainrBuilder with a Chainr specification. The spec is typically a List of Maps describing transforms.

```java
import com.bazaarvoice.jolt.chainr.ChainrBuilder;
import com.bazaarvoice.jolt.JsonUtils;

List<Object> spec = JsonUtils.classpathToList("/chainr/spec.json");
ChainrBuilder builder = new ChainrBuilder(spec);
```

--------------------------------

### Classpath-Based Methods

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/04-json-utilities.md

Methods for loading and parsing JSON resources from the application's classpath.

```APIDOC
## classpathToObject(String classPath)

### Description
Load and parse JSON from a resource located on the classpath.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
Object spec = JsonUtils.classpathToObject("/chainr/spec.json");
```

### Response
#### Success Response
- **spec** (Object) - Parsed JSON

#### Response Example
N/A
```

```APIDOC
## classpathToMap(String classPath)

### Description
Load a JSON resource from the classpath and parse it directly into a Map.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
Map<String, Object> chainrSpec = JsonUtils.classpathToMap("/specs/chainr.json");
```

### Response
#### Success Response
- **chainrSpec** (Map<String, Object>) - Parsed Map

#### Response Example
N/A
```

```APIDOC
## classpathToList(String classPath)

### Description
Load a JSON resource from the classpath and parse it directly into a List.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
List<Object> transforms = JsonUtils.classpathToList("/chainr/spec.json");
```

### Response
#### Success Response
- **transforms** (List<Object>) - Parsed List

#### Response Example
N/A
```

```APIDOC
## classpathToType(String classPath, TypeReference<T> typeRef)

### Description
Load a JSON resource from the classpath and deserialize it to a specific type using Jackson's `TypeReference`.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
List<Map<String, String>> data = JsonUtils.classpathToType(
    "/data.json", 
    new TypeReference<List<Map<String, String>>>() {}
);
```

### Response
#### Success Response
- **data** (T) - Deserialized object of type T

#### Response Example
N/A
```

```APIDOC
## classpathToType(String classPath, Class<T> aClass)

### Description
Load a JSON resource from the classpath and deserialize it to a specific class.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Java Method)

### Endpoint
N/A

### Request Example
```java
MyData data = JsonUtils.classpathToType("/config.json", MyData.class);
```

### Response
#### Success Response
- **data** (T) - Deserialized object of type T

#### Response Example
N/A
```

--------------------------------

### Generate Cobertura Code Coverage Report

Source: https://github.com/bazaarvoice/jolt/blob/master/README.md

Run the Cobertura plugin to generate a code coverage report. Open the generated HTML file to view the report.

```sh
mvn cobertura:cobertura
open jolt-core/target/site/cobertura/index.html
```

--------------------------------

### Load JSON File as List

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/04-json-utilities.md

Use this method to load a JSON file directly into a List. This is convenient when the JSON file's root is an array.

```java
List<Object> items = JsonUtils.filepathToList("/data.json");
```

--------------------------------

### Instantiate Diffy with Custom JsonUtil

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/05-diffy.md

Creates a Diffy instance with a custom JsonUtil for specific cloning requirements. This allows for more control over how JSON objects are cloned during the comparison.

```java
import com.bazaarvoice.jolt.JsonUtils;
import com.bazaarvoice.jolt.Diffy;

JsonUtil customUtil = JsonUtils.customJsonUtil(/* ObjectMapper */);
Diffy diffy = new Diffy(customUtil);
```

--------------------------------

### Catching Any Jolt Exception

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/07-exceptions.md

Demonstrates how to catch any Jolt-related error during a transformation process. This is useful for general error handling of Jolt operations.

```java
try {
    Chainr chainr = Chainr.fromSpec(spec);
    Object result = chainr.transform(input);
} catch (JoltException e) {
    // Catches any Jolt error
    System.err.println("Transformation failed: " + e.getMessage());
}
```

--------------------------------

### Build Chainr Instance

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/06-chainr-builder.md

Construct and return a fully initialized Chainr instance using the ChainrBuilder. This method is called after configuring the builder with spec, instantiator, and classloader.

```java
Chainr chainr = new ChainrBuilder(spec)
    .loader(customInstantiator)
    .withClassLoader(myClassLoader)
    .build();
```

--------------------------------

### Batch Process JSON Files with Jolt CLI

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

This script iterates through all JSON files in the current directory and applies a Jolt transformation to each. Transformed files are saved with a 'transformed-' prefix. This is useful for processing multiple files efficiently.

```bash
#!/bin/bash

for file in *.json; do
    echo "Processing $file..."
    jolt transform spec.json "$file" > "transformed-$file"
done
```

--------------------------------

### Jolt CLI - Large File Warning

Source: https://github.com/bazaarvoice/jolt/blob/master/_autodocs/09-cli-reference.md

The Jolt CLI loads the entire file into memory. For files larger than 1GB, consider using streaming alternatives or splitting the data.

```bash
# Jolt loads entire file into memory
# For files > 1GB, consider streaming alternatives or splitting data
```