Using DataSonnet Programmatically

DataSonnet is distributed as a JAR which contains all necessary classes and dependencies to use DataSonnet programmatically embedded in your projects. Use the following Maven snippet to add DataSonnet as a dependency to your pom.xml:

<dependency>
    <groupId>com.datasonnet</groupId>
    <artifactId>datasonnet-mapper</artifactId>
    <version>${datasonnet.version}</version>
</dependency>

where ${datasonnet.version} is the latest released version.

The simplest scenario is mapping from Java object to JSON with no additional variables:

String payload = "HelloWorld";
String script = """
    {
       "greetings": payload
    }
    """;
String expected = """
    {
       "greetings": "HelloWorld"
     }
    """;

Mapper mapper = new Mapper(script);
String result = mapper.transform(payload);

By default the input data will be interpreted as a Java object (in this example, a String) and the output format is JSON.

To transform complex data, it is recommended to use an overloaded transform method which accepts an instance of DefaultDocument object with media type that matches the input type, for example:

String json = """
    {
      "userId" : "123",
      "name" : "DataSonnet"
    }
    """;
String script = """
    {
       "uid": payload.userId,
       "uname": payload.name,
     }
    """;
String expected = """
    {
       "uid": "123",
       "uname": "DataSonnet"
     }
    """;

Mapper mapper = new Mapper(script);
String result = mapper.transform(new DefaultDocument<>(json, MediaTypes.APPLICATION_JSON)).getContent();

Aside from the payload, additional parameters (i.e. variables) may be passed to the transformation:

String payload = "{ \"greetings\": \"HelloWorld\"}";

String json = """
    {
      "userId" : "123",
      "name" : "DataSonnet"
    }
    """;

Map<String, Document<?>> variables = new HashMap<>();
variables.put("userData", new DefaultDocument<>(json, MediaTypes.APPLICATION_JSON));

String script = """
    {
       "greetings": payload.greetings,
       "uid": userData.userId,
       "uname": userData.name,
     }
    """;
String expected = """
    {
       "greetings": "HelloWorld",
       "uid": "123",
       "uname": "DataSonnet"
     }
    """;

Mapper mapper = new Mapper(script, variables.keySet());
String result = mapper.transform(new DefaultDocument<String>(payload, MediaTypes.APPLICATION_JSON), variables, MediaTypes.APPLICATION_JSON).getContent();

A mapper and/or transformation can also be created using the MapperBuilder class:

String payload = "{ \"greetings\": \"HelloWorld\"}";

String json = """
    {
      "userId" : "123",
      "name" : "DataSonnet"
    }
    """;

Map<String, Document<?>> variables = new HashMap<>();
variables.put("userData", new DefaultDocument<>(json, MediaTypes.APPLICATION_JSON));

String script = """
    local importedLib = import 'importTest.ds';

    {
       "greetings": payload.greetings,
       "sayHello": testlib.sayHello(),
       "uid": userData.userId,
       "uname": userData.name,
       "foo": importedLib.caps('foo')
     }
    """;
String expected = """
    {
       "greetings": "HelloWorld",
       "sayHello": "Hello, World",
       "uid": "123",
       "uname": "DataSonnet",
       "foo": "FOO"
     }
    """;

final String dsImport = TestResourceReader.readFileAsString("importTest.ds");

String result = new MapperBuilder(script)
        .withImports(Collections.singletonMap("importTest.ds", dsImport))
        .withLibrary(TestLib.getInstance())
        .withInputNames(variables.keySet())
        .build()
        .transform(new DefaultDocument<String>(payload, MediaTypes.APPLICATION_JSON), variables, MediaTypes.APPLICATION_JSON).getContent();

For more examples of programmatic DataSonnet usages please refer to the tests part of the DataSonnet source code at https://github.com/datasonnet/datasonnet-mapper/tree/main/src/test