net.jqwik.api.statistics.StatisticsReport Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jqwik-api Show documentation

Jqwik API module

There is a newer version: 1.9.2

package net.jqwik.api.statistics;

import java.lang.annotation.*;
import java.util.*;

import org.apiguardian.api.*;

import static org.apiguardian.api.API.Status.*;

/**
 * This annotation can be used to influence statistics reporting. You can either
 * annotate a property method to change reporting for this property only
 * or a container class to change reporting for all properties in this class
 * or nested subclasses.
 * 
 * There are three usage scenarios:
 * 

 *     
 *          Use {@code @StatisticsReport(STANDARD)} to enable the standard reporting.
 *  		This is the default anyway.
 *  	
 *  	
 * 			Use {@code @StatisticsReport(OFF)} to disable statistics reporting.
 *  	
 *  	
 * 			Use {@code @StatisticsReport(format = YourReportFormat.class)} to plug in your own format.
 *  	
 * 
 *
 * 
 *     This annotation is repeatable when used on property methods.
 *     In this case use {@linkplain #label()} to specify for which statistics collection the given report format shall be used.
 * 
 *
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Repeatable(StatisticsReportList.class)
@API(status = EXPERIMENTAL, since = "1.2.3")
public @interface StatisticsReport {

	@API(status = INTERNAL)
	class None implements StatisticsReportFormat {
		@Override
		public List formatReport(List entries) {
			throw new UnsupportedOperationException("This format should never be used");
		}
	}

	enum StatisticsReportMode {
		/**
		 * No statistics report
		 */
		OFF,
		/**
		 * Standard statistics report format
		 */
		STANDARD,
		/**
		 * Plug in your own format. Must be set with {@linkplain StatisticsReport#format()}.
		 */
		PLUG_IN
	}

	String ALL_LABELS = "";

	StatisticsReportMode value() default StatisticsReportMode.PLUG_IN;

	/**
	 * The format to be used for publishing statistics reports
	 * in the annotated property.
	 */
	Class format() default None.class;

	/**
	 * The statistics label to which the format in this annotation should be applied.
	 */
	@API(status = EXPERIMENTAL, since = "1.5.1")
	String label() default ALL_LABELS;
}