8. Customization
Prev |  | Next

# 8. Customization

## 8.1 Extending the DSL

It is possible to provide your own functions to the DSL. The key requirement for this feature was to maintain the static compatibility. Below you will be able to see an example of:

- creation of a JAR with reusable classes
- referencing of these classes in the DSLs

The full example can be found here.

### 8.1.1 Common JAR

Below you can find three classes that we will reuse in the DSLs.

PatternUtils contains functions used by both the consumer and the producer.

    package com.example;

    import java.util.regex.Pattern;

    /**
     * If you want to use {@link Pattern} directly in your tests
     * then you can create a class resembling this one. It can
     * contain all the {@link Pattern} you want to use in the DSL.
     *
     * <pre>
     * {@code
     * request {
     *     body(
     *         [ age: $(c(PatternUtils.oldEnough()))]
     *     )
     * }
     * </pre>
     *
     * Notice that we're using both {@code $()} for dynamic values
     * and {@code c()} for the consumer side.
     *
     * @author Marcin Grzejszczak
     */
    //tag::impl[]
    public class PatternUtils {

    	public static String tooYoung() {
    		//remove::start[]
    		return "[0-1][0-9]";
    		//remove::end[return]
    	}

    	public static Pattern oldEnough() {
    		//remove::start[]
    		return Pattern.compile("[2-9][0-9]");
    		//remove::end[return]
    	}

    	/**
    	 * Makes little sense but it's just an example ;)
    	 */
    	public static Pattern ok() {
    		//remove::start[]
    		return Pattern.compile("OK");
    		//remove::end[return]
    	}
    }
    //end::impl[]

ConsumerUtils contains functions used by the consumer.

    package com.example;

    import org.springframework.cloud.contract.spec.internal.ClientDslProperty;

    /**
     * DSL Properties passed to the DSL from the consumer's perspective.
     * That means that on the input side {@code Request} for HTTP
     * or {@code Input} for messaging you can have a regular expression.
     * On the {@code Response} for HTTP or {@code Output} for messaging
     * you have to have a concrete value.
     *
     * @author Marcin Grzejszczak
     */
    //tag::impl[]
    public class ConsumerUtils {
    	/**
    	 * Consumer side property. By using the {@link ClientDslProperty}
    	 * you can omit most of boilerplate code from the perspective
    	 * of dynamic values. Example
    	 *
    	 * <pre>
    	 * {@code
    	 * request {
    	 *     body(
    	 *         [ age: $(ConsumerUtils.oldEnough())]
    	 *     )
    	 * }
    	 * </pre>
    	 *
    	 * That way it's in the implementation that we decide what value we will pass to the consumer
    	 * and which one to the producer.
    	 *
    	 * @author Marcin Grzejszczak
    	 */
    	public static ClientDslProperty oldEnough() {
    		//remove::start[]
    		// this example is not the best one and
    		// theoretically you could just pass the regex instead of `ServerDslProperty` but
    		// it's just to show some new tricks :)
    		return new ClientDslProperty(PatternUtils.oldEnough(), 40);
    		//remove::end[return]
    	}

    }
    //end::impl[]

ProducerUtils contains functions used by the producer.

    package com.example;

    import org.springframework.cloud.contract.spec.internal.ServerDslProperty;

    /**
     * DSL Properties passed to the DSL from the producer's perspective.
     * That means that on the input side {@code Request} for HTTP
     * or {@code Input} for messaging you have to have a concrete value.
     * On the {@code Response} for HTTP or {@code Output} for messaging
     * you can have a regular expression.
     *
     * @author Marcin Grzejszczak
     */
    //tag::impl[]
    public class ProducerUtils {

    	/**
    	 * Producer side property. By using the {@link ProducerUtils}
    	 * you can omit most of boilerplate code from the perspective
    	 * of dynamic values. Example
    	 *
    	 * <pre>
    	 * {@code
    	 * response {
    	 *     body(
    	 *         [ status: $(ProducerUtils.ok())]
    	 *     )
    	 * }
    	 * </pre>
    	 *
    	 * That way it's in the implementation that we decide what value we will pass to the consumer
    	 * and which one to the producer.
    	 */
    	public static ServerDslProperty ok() {
    		// this example is not the best one and
    		// theoretically you could just pass the regex instead of `ServerDslProperty` but
    		// it's just to show some new tricks :)
    		return new ServerDslProperty( PatternUtils.ok(), "OK");
    	}
    }
    //end::impl[]

### 8.1.2 Adding the dependency to project

In order for the plugins and IDE to be able to reference the common JAR classes you need to pass the dependency to your project.

### 8.1.3 Test dependency in project’s dependencies

First add the common jar dependency as a test dependency. That way since your contracts files are available at test resources path, automatically the common jar classes will be visible in your Groovy files.

Maven.

    <dependency>
    	<groupId>com.example</groupId>
    	<artifactId>beer-common</artifactId>
    	<version>${project.version}</version>
    	<scope>test</scope>
    </dependency>

Gradle.

    testCompile("com.example:beer-common:0.0.1-SNAPSHOT")

### 8.1.4 Test dependency in plugin’s dependencies

Now you have to add the dependency for the plugin to reuse at runtime.

Maven.

    <plugin>
    	<groupId>org.springframework.cloud</groupId>
    	<artifactId>spring-cloud-contract-maven-plugin</artifactId>
    	<version>${spring-cloud-contract.version}</version>
    	<extensions>true</extensions>
    	<configuration>
    		<packageWithBaseClasses>com.example</packageWithBaseClasses>
    		<baseClassMappings>
    			<baseClassMapping>
    				<contractPackageRegex>.*intoxication.*</contractPackageRegex>
    				<baseClassFQN>com.example.intoxication.BeerIntoxicationBase</baseClassFQN>
    			</baseClassMapping>
    		</baseClassMappings>
    	</configuration>
    	<dependencies>
    		<dependency>
    			<groupId>com.example</groupId>
    			<artifactId>beer-common</artifactId>
    			<version>${project.version}</version>
    			<scope>compile</scope>
    		</dependency>
    	</dependencies>
    </plugin>

Gradle.

    classpath "com.example:beer-common:0.0.1-SNAPSHOT"

### 8.1.5 Referencing classes in DSLs

Now you can reference your classes in your DSL. Example:

    package contracts.beer.rest

    import com.example.ConsumerUtils
    import com.example.ProducerUtils
    import org.springframework.cloud.contract.spec.Contract

    Contract.make {
    	description("""
    Represents a successful scenario of getting a beer

    ```
    given:
    	client is old enough
    when:
    	he applies for a beer
    then:
    	we'll grant him the beer
    ```

    """)
    	request {
    		method 'POST'
    		url '/check'
    		body(
    				age: $(ConsumerUtils.oldEnough())
    		)
    		headers {
    			contentType(applicationJson())
    		}
    	}
    	response {
    		status 200
    		body("""
    			{
    				"status": "${value(ProducerUtils.ok())}"
    			}
    			""")
    		headers {
    			contentType(applicationJson())
    		}
    	}
    }

Prev |  | Next
7. Contract DSL | Home | 9. Pluggable architecture