io.pactfoundation.consumer.dsl.LambdaDslObject Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of pact-jvm-consumer-java8_2.12 Show documentation
Show all versions of pact-jvm-consumer-java8_2.12 Show documentation
# pact-jvm-consumer-java8
Provides a Java8 lambda based DSL for use with Junit to build consumer tests.
# A Lambda DSL for Pact
This is an extension for the pact DSL provided by [pact-jvm-consumer](../pact-jvm-consumer). The difference between
the default pact DSL and this lambda DSL is, as the name suggests, the usage of lambdas. The use of lambdas makes the code much cleaner.
## Why a new DSL implementation?
The lambda DSL solves the following two main issues. Both are visible in the following code sample:
```java
new PactDslJsonArray()
.array() # open an array
.stringValue("a1") # choose the method that is valid for arrays
.stringValue("a2") # choose the method that is valid for arrays
.closeArray() # close the array
.array() # open an array
.numberValue(1) # choose the method that is valid for arrays
.numberValue(2) # choose the method that is valid for arrays
.closeArray() # close the array
.array() # open an array
.object() # now we work with an object
.stringValue("foo", "Foo") # choose the method that is valid for objects
.closeObject() # close the object and we're back in the array
.closeArray() # close the array
```
### The existing DSL is quite error-prone
Methods may only be called in certain states. For example `object()` may only be called when you're currently working on an array whereas `object(name)`
is only allowed to be called when working on an object. But both of the methods are available. You'll find out at runtime if you're using the correct method.
Finally, the need for opening and closing objects and arrays makes usage cumbersome.
The lambda DSL has no ambiguous methods and there's no need to close objects and arrays as all the work on such an object is wrapped in a lamda call.
### The existing DSL is hard to read
When formatting your source code with an IDE the code becomes hard to read as there's no indentation possible. Of course, you could do it by hand but we want auto formatting!
Auto formatting works great for the new DSL!
```java
array.object((o) -> {
o.stringValue("foo", "Foo"); # an attribute
o.stringValue("bar", "Bar"); # an attribute
o.object("tar", (tarObject) -> { # an attribute with a nested object
tarObject.stringValue("a", "A"); # attribute of the nested object
tarObject.stringValue("b", "B"); # attribute of the nested object
})
});
```
## Installation
### Maven
```
<dependency>
<groupId>au.com.dius</groupId>
<artifactId>pact-jvm-consumer-java8</artifactId>
<version>${pact.version}</version>
</dependency>
```
## Usage
Start with a static import of `LambdaDsl`. This class contains factory methods for the lambda dsl extension.
When you come accross the `body()` method of `PactDslWithProvider` builder start using the new extensions.
The call to `LambdaDsl` replaces the call to instance `new PactDslJsonArray()` and `new PactDslJsonBody()` of the pact library.
```java
io.pactfoundation.consumer.dsl.LambdaDsl.*
```
### Response body as json array
```java
import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonArray;
...
PactDslWithProvider builder = ...
builder.given("some state")
.uponReceiving("a request")
.path("/my-app/my-service")
.method("GET")
.willRespondWith()
.status(200)
.body(newJsonArray((a) -> {
a.stringValue("a1");
a.stringValue("a2");
}).build());
```
### Response body as json object
```java
import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonBody;
...
PactDslWithProvider builder = ...
builder.given("some state")
.uponReceiving("a request")
.path("/my-app/my-service")
.method("GET")
.willRespondWith()
.status(200)
.body(newJsonBody((o) -> {
o.stringValue("foo", "Foo");
o.stringValue("bar", "Bar");
}).build());
```
### Examples
#### Simple Json object
When creating simple json structures the difference between the two approaches isn't big.
##### JSON
```json
{
"bar": "Bar",
"foo": "Foo"
}
```
##### Pact DSL
```java
new PactDslJsonBody()
.stringValue("foo", "Foo")
.stringValue("bar", "Bar")
```
##### Lambda DSL
```java
newJsonBody((o) -> {
o.stringValue("foo", "Foo");
o.stringValue("bar", "Bar");
}).build()
```
#### An array of arrays
When we come to more complex constructs with arrays and nested objects the beauty of lambdas become visible!
##### JSON
```json
[
["a1", "a2"],
[1, 2],
[{"foo": "Foo"}]
]
```
##### Pact DSL
```java
new PactDslJsonArray()
.array()
.stringValue("a1")
.stringValue("a2")
.closeArray()
.array()
.numberValue(1)
.numberValue(2)
.closeArray()
.array()
.object()
.stringValue("foo", "Foo")
.closeObject()
.closeArray()
```
##### Lambda DSL
```java
newJsonArray((rootArray) -> {
rootArray.array((a) -> a.stringValue("a1").stringValue("a2"));
rootArray.array((a) -> a.numberValue(1).numberValue(2));
rootArray.array((a) -> a.object((o) -> o.stringValue("foo", "Foo"));
}).build()
```
package io.pactfoundation.consumer.dsl;
import au.com.dius.pact.consumer.dsl.PactDslJsonArray;
import au.com.dius.pact.consumer.dsl.PactDslJsonBody;
import au.com.dius.pact.consumer.dsl.PactDslJsonRootValue;
import au.com.dius.pact.model.matchingrules.MatchingRule;
import java.math.BigDecimal;
import java.time.Instant;
import java.time.ZonedDateTime;
import java.util.Date;
import java.util.TimeZone;
import java.util.UUID;
import java.util.function.Consumer;
public class LambdaDslObject {
private final PactDslJsonBody object;
LambdaDslObject(final PactDslJsonBody object) {
this.object = object;
}
public LambdaDslObject stringValue(final String name, final String value) {
object.stringValue(name, value);
return this;
}
public LambdaDslObject stringType(final String name, final String example) {
object.stringType(name, example);
return this;
}
public LambdaDslObject stringType(final String name) {
object.stringType(name);
return this;
}
public LambdaDslObject stringType(final String... names) {
object.stringType(names);
return this;
}
public LambdaDslObject stringMatcher(final String name, final String example) {
object.stringMatcher(name, example);
return this;
}
public LambdaDslObject stringMatcher(final String name, final String regex, final String value) {
object.stringMatcher(name, regex, value);
return this;
}
public LambdaDslObject numberValue(final String name, final Number value) {
object.numberValue(name, value);
return this;
}
public LambdaDslObject numberType(final String name, final Number example) {
object.numberType(name, example);
return this;
}
public LambdaDslObject numberType(final String... names) {
object.numberType(names);
return this;
}
public LambdaDslObject decimalType(final String name, final BigDecimal value) {
object.decimalType(name, value);
return this;
}
public LambdaDslObject decimalType(final String name, final Double example) {
object.decimalType(name, example);
return this;
}
public LambdaDslObject decimalType(final String... names) {
object.decimalType(names);
return this;
}
public LambdaDslObject booleanValue(final String name, final Boolean value) {
object.booleanValue(name, value);
return this;
}
public LambdaDslObject booleanType(final String name, final Boolean example) {
object.booleanType(name, example);
return this;
}
public LambdaDslObject booleanType(final String... names) {
object.booleanType(names);
return this;
}
public LambdaDslObject id() {
object.id();
return this;
}
public LambdaDslObject id(final String name) {
object.id(name);
return this;
}
public LambdaDslObject id(final String name, Long id) {
object.id(name, id);
return this;
}
public LambdaDslObject uuid(final String name) {
object.uuid(name);
return this;
}
public LambdaDslObject uuid(final String name, UUID id) {
object.uuid(name, id);
return this;
}
/**
* Attribute named 'date' that must be formatted as an ISO date
*/
public LambdaDslObject date() {
object.date();
return this;
}
/**
* Attribute that must be formatted as an ISO date
*
* @param name attribute name
*/
public LambdaDslObject date(String name) {
object.date(name);
return this;
}
/**
* Attribute that must match the provided date format
*
* @param name attribute date
* @param format date format to match
*/
public LambdaDslObject date(String name, String format) {
object.date(name, format);
return this;
}
/**
* Attribute that must match the provided date format
*
* @param name attribute date
* @param format date format to match
* @param example example date to use for generated values
*/
public LambdaDslObject date(String name, String format, Date example) {
object.date(name, format, example);
return this;
}
/**
* Attribute that must match the provided date format
*
* @param name attribute date
* @param format date format to match
* @param example example date to use for generated values
* @param timeZone time zone used for formatting of example date
*/
public LambdaDslObject date(String name, String format, Date example, TimeZone timeZone) {
object.date(name, format, example, timeZone);
return this;
}
/**
* Attribute that must match the provided date format
*
* @param name attribute date
* @param format date format to match
* @param example example date to use for generated values
*/
public LambdaDslObject date(String name, String format, ZonedDateTime example) {
object.date(name, format, Date.from(example.toInstant()), TimeZone.getTimeZone(example.getZone()));
return this;
}
/**
* Attribute named 'time' that must be an ISO formatted time
*/
public LambdaDslObject time() {
object.time();
return this;
}
/**
* Attribute that must be an ISO formatted time
*
* @param name attribute name
*/
public LambdaDslObject time(String name) {
object.time(name);
return this;
}
/**
* Attribute that must match the provided time format
*
* @param name attribute time
* @param format time format to match
*/
public LambdaDslObject time(String name, String format) {
object.time(name, format);
return this;
}
/**
* Attribute that must match the provided time format
*
* @param name attribute name
* @param format time format to match
* @param example example time to use for generated values
*/
public LambdaDslObject time(String name, String format, Date example) {
object.time(name, format, example);
return this;
}
/**
* Attribute that must match the provided time format
*
* @param name attribute name
* @param format time format to match
* @param example example time to use for generated values
* @param timeZone time zone used for formatting of example time
*/
public LambdaDslObject time(String name, String format, Date example, TimeZone timeZone) {
object.time(name, format, example, timeZone);
return this;
}
/**
* Attribute that must match the provided time format
*
* @param name attribute name
* @param format time format to match
* @param example example time to use for generated values
*/
public LambdaDslObject time(String name, String format, ZonedDateTime example) {
object.time(name, format, Date.from(example.toInstant()), TimeZone.getTimeZone(example.getZone()));
return this;
}
/**
* Attribute named 'timestamp' that must be an ISO formatted timestamp
*/
public LambdaDslObject timestamp() {
object.timestamp();
return this;
}
/**
* Attribute that must be an ISO formatted timestamp
*
* @param name attribute name
*/
public LambdaDslObject timestamp(String name) {
object.timestamp(name);
return this;
}
/**
* Attribute that must match the given timestamp format
*
* @param name attribute name
* @param format timestamp format
*/
public LambdaDslObject timestamp(String name, String format) {
object.timestamp(name, format);
return this;
}
/**
* Attribute that must match the given timestamp format
*
* @param name attribute name
* @param format timestamp format
* @param example example date and time to use for generated bodies
*/
public LambdaDslObject timestamp(String name, String format, Date example) {
object.timestamp(name, format, example);
return this;
}
/**
* Attribute that must match the given timestamp format
*
* @param name attribute name
* @param format timestamp format
* @param example example date and time to use for generated bodies
*/
public LambdaDslObject timestamp(String name, String format, Instant example) {
object.timestamp(name, format, example);
return this;
}
/**
* Attribute that must match the given timestamp format
*
* @param name attribute name
* @param format timestamp format
* @param example example date and time to use for generated bodies
* @param timeZone time zone used for formatting of example date and time
*/
public LambdaDslObject timestamp(String name, String format, Date example, TimeZone timeZone){
object.timestamp(name, format, example, timeZone);
return this;
}
/**
* Attribute that must match the given timestamp format
*
* @param name attribute name
* @param format timestamp format
* @param example example date and time to use for generated bodies
*/
public LambdaDslObject timestamp(String name, String format, ZonedDateTime example) {
object.timestamp(name, format, Date.from(example.toInstant()), TimeZone.getTimeZone(example.getZone()));
return this;
}
/**
* Attribute that must be an IP4 address
*
* @param name attribute name
*/
public LambdaDslObject ipV4Address(String name) {
object.ipAddress(name);
return this;
}
/** Combine all the matchers using AND
* @param name Attribute name
* @param value Attribute example value
* @param rules Matching rules to apply
* @return
*/
public LambdaDslObject and(String name, Object value, MatchingRule... rules) {
object.and(name, value, rules);
return this;
}
/**
* Combine all the matchers using OR
* @param name Attribute name
* @param value Attribute example value
* @param rules Matching rules to apply
* @return
*/
public LambdaDslObject or(String name, Object value, MatchingRule... rules) {
object.or(name, value, rules);
return this;
}
public LambdaDslObject array(final String name, final Consumer array) {
final PactDslJsonArray pactArray = object.array(name);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(pactArray);
array.accept(dslArray);
pactArray.closeArray();
return this;
}
public LambdaDslObject object(final String name, final Consumer nestedObject) {
final PactDslJsonBody pactObject = object.object(name);
final LambdaDslObject dslObject = new LambdaDslObject(pactObject);
nestedObject.accept(dslObject);
pactObject.closeObject();
return this;
}
/**
* Attribute that is an array where each item must match the following example
*
* @param name field name
*/
public LambdaDslObject eachLike(String name, Consumer nestedObject) {
final PactDslJsonBody arrayLike = object.eachLike(name);
final LambdaDslObject dslObject = new LambdaDslObject(arrayLike);
nestedObject.accept(dslObject);
arrayLike.closeArray();
return this;
}
/**
* Attribute that is an array where each item must match the following example
*
* @param name field name
* @param numberExamples number of examples to generate
*/
public LambdaDslObject eachLike(String name, int numberExamples, Consumer nestedObject) {
final PactDslJsonBody arrayLike = object.eachLike(name, numberExamples);
final LambdaDslObject dslObject = new LambdaDslObject(arrayLike);
nestedObject.accept(dslObject);
arrayLike.closeArray();
return this;
}
/**
* Attribute that is an array where each item is a primitive that must match the provided value
*
* @param name field name
* @param value Value that each item in the array must match
*/
public LambdaDslObject eachLike(String name, PactDslJsonRootValue value) {
object.eachLike(name, value);
return this;
}
/**
* Attribute that is an array where each item is a primitive that must match the provided value
*
* @param name field name
* @param value Value that each item in the array must match
* @param numberExamples Number of examples to generate
*/
public LambdaDslObject eachLike(String name, PactDslJsonRootValue value, int numberExamples) {
object.eachLike(name, value, numberExamples);
return this;
}
/**
* Attribute that is an array with a minimum size where each item must match the following example
*
* @param name field name
* @param size minimum size of the array
*/
public LambdaDslObject minArrayLike(String name, Integer size, Consumer nestedObject) {
final PactDslJsonBody minArrayLike = object.minArrayLike(name, size);
final LambdaDslObject dslObject = new LambdaDslObject(minArrayLike);
nestedObject.accept(dslObject);
minArrayLike.closeArray();
return this;
}
/**
* Attribute that is an array with a minimum size where each item must match the following example
*
* @param name field name
* @param size minimum size of the array
* @param numberExamples number of examples to generate
*/
public LambdaDslObject minArrayLike(String name, Integer size, int numberExamples,
Consumer nestedObject) {
final PactDslJsonBody minArrayLike = object.minArrayLike(name, size, numberExamples);
final LambdaDslObject dslObject = new LambdaDslObject(minArrayLike);
nestedObject.accept(dslObject);
minArrayLike.closeArray();
return this;
}
/**
* Attribute that is an array of values with a minimum size that are not objects where each item must match
* the following example
* @param name field name
* @param size minimum size of the array
* @param value Value to use to match each item
* @param numberExamples number of examples to generate
*/
public LambdaDslObject minArrayLike(String name, Integer size, PactDslJsonRootValue value, int numberExamples) {
object.minArrayLike(name, size, value, numberExamples);
return this;
}
/**
* Attribute that is an array with a maximum size where each item must match the following example
*
* @param name field name
* @param size maximum size of the array
*/
public LambdaDslObject maxArrayLike(String name, Integer size, Consumer nestedObject) {
final PactDslJsonBody maxArrayLike = object.maxArrayLike(name, size);
final LambdaDslObject dslObject = new LambdaDslObject(maxArrayLike);
nestedObject.accept(dslObject);
maxArrayLike.closeArray();
return this;
}
/**
* Attribute that is an array with a maximum size where each item must match the following example
*
* @param name field name
* @param size maximum size of the array
* @param numberExamples number of examples to generate
*/
public LambdaDslObject maxArrayLike(String name, Integer size, int numberExamples,
Consumer nestedObject) {
final PactDslJsonBody maxArrayLike = object.maxArrayLike(name, size, numberExamples);
final LambdaDslObject dslObject = new LambdaDslObject(maxArrayLike);
nestedObject.accept(dslObject);
maxArrayLike.closeArray();
return this;
}
/**
* Attribute that is an array of values with a maximum size that are not objects where each item must match the
* following example
* @param name field name
* @param size maximum size of the array
* @param value Value to use to match each item
* @param numberExamples number of examples to generate
*/
public LambdaDslObject maxArrayLike(String name, Integer size, PactDslJsonRootValue value, int numberExamples) {
object.maxArrayLike(name, size, value, numberExamples);
return this;
}
/**
* Attribute that is an array with a minimum and maximum size where each item must match the following example
*
* @param name field name
* @param minSize minimum size of the array
* @param maxSize maximum size of the array
*/
public LambdaDslObject minMaxArrayLike(String name, Integer minSize, Integer maxSize, Consumer nestedObject) {
final PactDslJsonBody maxArrayLike = object.minMaxArrayLike(name, minSize, maxSize);
final LambdaDslObject dslObject = new LambdaDslObject(maxArrayLike);
nestedObject.accept(dslObject);
maxArrayLike.closeArray();
return this;
}
/**
* Attribute that is an array with a minimum and maximum size where each item must match the following example
*
* @param name field name
* @param minSize minimum size of the array
* @param maxSize maximum size of the array
* @param numberExamples number of examples to generate
*/
public LambdaDslObject minMaxArrayLike(String name, Integer minSize, Integer maxSize, int numberExamples,
Consumer nestedObject) {
final PactDslJsonBody maxArrayLike = object.minMaxArrayLike(name, minSize, maxSize, numberExamples);
final LambdaDslObject dslObject = new LambdaDslObject(maxArrayLike);
nestedObject.accept(dslObject);
maxArrayLike.closeArray();
return this;
}
/**
* Attribute that is an array of values with a minimum and maximum size that are not objects where each item must
* match the following example
* @param name field name
* @param minSize minimum size of the array
* @param maxSize maximum size of the array
* @param value Value to use to match each item
* @param numberExamples number of examples to generate
*/
public LambdaDslObject minMaxArrayLike(String name, Integer minSize, Integer maxSize, PactDslJsonRootValue value,
int numberExamples) {
object.minMaxArrayLike(name, minSize, maxSize, value, numberExamples);
return this;
}
/**
* Sets the field to a null value
*
* @param fieldName field name
*/
public LambdaDslObject nullValue(String fieldName) {
object.nullValue(fieldName);
return this;
}
public LambdaDslObject eachArrayLike(String name, Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayLike(name);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayLike(String name, int numberExamples, Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayLike(name, numberExamples);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayWithMaxLike(String name, Integer size, Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayWithMaxLike(name, size);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayWithMaxLike(String name, int numberExamples, Integer size,
Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayWithMaxLike(name, numberExamples, size);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayWithMinLike(String name, Integer size, Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayWithMinLike(name, size);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayWithMinLike(String name, int numberExamples, Integer size,
Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayWithMinLike(name, numberExamples, size);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayWithMinMaxLike(String name, Integer minSize, Integer maxSize, Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayWithMinMaxLike(name, minSize, maxSize);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
public LambdaDslObject eachArrayWithMinMaxLike(String name, Integer minSize, Integer maxSize, int numberExamples,
Consumer nestedArray) {
final PactDslJsonArray arrayLike = object.eachArrayWithMinMaxLike(name, numberExamples, minSize, maxSize);
final LambdaDslJsonArray dslArray = new LambdaDslJsonArray(arrayLike);
nestedArray.accept(dslArray);
arrayLike.closeArray().closeArray();
return this;
}
/**
* Accepts any key, and each key is mapped to a list of items that must match the following object definition.
* Note: this needs the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.
*
* @param exampleKey Example key to use for generating bodies
*/
public LambdaDslObject eachKeyMappedToAnArrayLike(String exampleKey, Consumer nestedObject) {
final PactDslJsonBody objectLike = object.eachKeyMappedToAnArrayLike(exampleKey);
final LambdaDslObject dslObject = new LambdaDslObject(objectLike);
nestedObject.accept(dslObject);
objectLike.closeObject().closeArray();
return this;
}
/**
* Accepts any key, and each key is mapped to a map that must match the following object definition.
* Note: this needs the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.
*
* @param exampleKey Example key to use for generating bodies
*/
public LambdaDslObject eachKeyLike(String exampleKey, Consumer nestedObject) {
final PactDslJsonBody objectLike = object.eachKeyLike(exampleKey);
final LambdaDslObject dslObject = new LambdaDslObject(objectLike);
nestedObject.accept(dslObject);
objectLike.closeObject();
return this;
}
/**
* Accepts any key, and each key is mapped to a map that must match the provided object definition
* Note: this needs the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.
* @param exampleKey Example key to use for generating bodies
* @param value Value to use for matching and generated bodies
*/
public LambdaDslObject eachKeyLike(String exampleKey, PactDslJsonRootValue value) {
object.eachKeyLike(exampleKey, value);
return this;
}
}