Commit e9e2356c authored by Lubomir Bulej's avatar Lubomir Bulej

DiSL: Updated annotation descriptions and metadata.

parent 763be53b
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* The After annotation instructs DiSL to insert the snippet body after the
* marked region. The snippet will be invoked after a normal exit of the region
* or after an exit caused by an exception.
*
* NOTE: This is only general contract. It depends on particular marker how the
* contract will be implemented.
*
* Marks DiSL snippet to be inserted after the marked code region. The snippet
* will be executed both after normal or exceptional exit from the marked code
* region.
* <p>
* NOTE: This is a general contract. The actual implementation depends on the
* particular marker used with the snippet.
* <p>
* This annotation should be used with methods.
*
* The method should be static, not return any values and not throw any
* exceptions.
*
* Method argument can be StaticContext, DynamicContext, ClassContext and
* ArgumentProcessorContext.
* <p>
* The snippet method must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* Supported method argument types include {@link StaticContext},
* {@link DynamicContext}, {@link ClassContext}, and
* {@link ArgumentProcessorContext}.
*/
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.CLASS)
public @interface After {
// NOTE if you want to change names, you need to change
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
/**
* Marker class defines a region where the snippet is applied.
* Marker class. Determines the region of code where to apply the snippet.
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Argument for the marker (as string).
*
* <p>
* Default value: ""
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Scope of the methods, where the snippet is applied.
*
* <p>
* @see ch.usi.dag.disl.scope package for more info about scoping language.
*
* <p>
* Default value: "*"
*/
String scope() default "*";
/**
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* Default value: Object.class - means none
* <p>
* Default value: void.class - means none
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* Determines snippet ordering. Smaller number indicates that snippet
* will be inlined closer to the marked code region.
* <p>
* Default value: 100
*/
int order() default 100;
/**
* Advanced option. You can in general disable dynamic bypass on snippets,
* that are not using any other class.
*
* NOTE Usage of dynamic bypass is determined by the underlying
* <p>
* NOTE: Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
*
* <p>
* Default value: true
*/
boolean dynamicBypass() default true;
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* The AfterReturning annotation instructs DiSL to insert the snippet body after
* the marked region. The snippet will be invoked after a normal exit of the
* region.
*
* NOTE: This is only general contract. It depends on particular marker how the
* contract will be implemented.
*
* Marks DiSL snippet to be inserted after the marked code region. The snippet
* will be executed after normal exit from the marked code region.
* <p>
* NOTE: This is a general contract. The actual implementation depends on the
* particular marker used with the snippet.
* <p>
* This annotation should be used with methods.
*
* The method should be static, not return any values and not throw any
* exceptions.
*
* Method argument can be StaticContext, DynamicContext, ClassContext and
* ArgumentProcessorContext.
* <p>
* The snippet method must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* Supported method argument types include {@link StaticContext},
* {@link DynamicContext}, {@link ClassContext}, and
* {@link ArgumentProcessorContext}.
*/
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.CLASS)
public @interface AfterReturning {
// NOTE if you want to change names, you need to change
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
/**
* Marker class defines a region where the snippet is applied.
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Argument for the marker (as string).
*
* <p>
* Default value: ""
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Scope of the methods, where the snippet is applied.
*
* <p>
* @see ch.usi.dag.disl.scope package for more info about scoping language.
*
* <p>
* Default value: "*"
*/
String scope() default "*";
/**
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* Default value: Object.class - means none
* <p>
* Default value: void.class - means none
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* Determines snippet ordering. Smaller number indicates that snippet
* will be inlined closer to the marked code region.
* <p>
* Default value: 100
*/
int order() default 100;
/**
* Advanced option. You can in general disable dynamic bypass on snippets,
* that are not using any other class.
*
* NOTE Usage of dynamic bypass is determined by the underlying
* <p>
* NOTE: Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
*
* <p>
* Default value: true
*/
boolean dynamicBypass() default true;
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* The AfterThrowing annotation instructs DiSL to insert the snippet body after
* the marked region. The snippet will be invoked after an exit caused by an
* exception.
*
* NOTE: This is only general contract. It depends on particular marker how the
* contract will be implemented.
*
* Marks DiSL snippet to be inserted after the marked code region. The snippet
* will be executed after exceptional exit from the marked code region.
* <p>
* NOTE: This is a general contract. The actual implementation depends on the
* particular marker used with the snippet.
* <p>
* This annotation should be used with methods.
*
* The method should be static, not return any values and not throw any
* exceptions.
*
* Method argument can be StaticContext, DynamicContext, ClassContext and
* ArgumentProcessorContext.
* <p>
* The snippet method must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* Supported method argument types include {@link StaticContext},
* {@link DynamicContext}, {@link ClassContext}, and
* {@link ArgumentProcessorContext}.
*/
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.CLASS)
public @interface AfterThrowing {
// NOTE if you want to change names, you need to change
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
/**
* Marker class defines a region where the snippet is applied.
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Argument for the marker (as string).
*
* <p>
* Default value: ""
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Scope of the methods, where the snippet is applied.
*
* <p>
* @see ch.usi.dag.disl.scope package for more info about scoping language.
*
* <p>
* Default value: "*"
*/
String scope() default "*";
/**
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* Default value: Object.class - means none
* <p>
* Default value: void.class - means none
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* Determines snippet ordering. Smaller number indicates that snippet
* will be inlined closer to the marked code region.
* <p>
* Default value: 100
*/
int order() default 100;
/**
* Advanced option. You can in general disable dynamic bypass on snippets,
* that are not using any other class.
*
* <p>
* NOTE Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
*
* <p>
* Default value: true
*/
boolean dynamicBypass() default true;
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Annotated class defines method for processing method arguments. The specified
* methods will be inlined into snippets to process one method argument value.
*
* First argument of the method is a type, that will be processed by the method.
* The allowed types are all basic types, String and Object class. The processed
* type can be extend in some special cases by ProcessAlso annotation.
* During run-time, the argument will contain a processed method argument value.
*
* ArgumentContext can be used to fetch additional data about the argument.
*
* This annotation should be used with classes.
*
* The method should be static, not return any values and not throw any
* exceptions.
*
* Method argument can be StaticContext, DynamicContext, ClassContext and
* ArgumentContext.
* Indicates that the class contains methods for processing method arguments
* with corresponding types. Methods corresponding to argument types will be
* invoked with the type and value of the argument. The invocations of the
* argument processor methods will be inlined into each snippet that uses the
* argument processor.
* <p>
* An argument processor <b>method</b> has the argument type as its first
* parameter. Only primitive, {@link String}, and {@link Object} types are
* allowed. In some cases, the type accepted by the argument processor method
* can be extended using the {@link ProcessAlso} annotation. At runtime, the
* second parameter of the argument processor will contain the value of the
* argument being processed.
* <p>
* Additional information (e.g. position) about the argument can be obtained
* using the {@link ArgumentContext} interface. To use it, an argument processor
* method must have a parameter of type {@link ArgumentContext}. Other allowed
* contexts are {@link StaticContext}, {@link DynamicContext}, and
* {@link ClassContext}.
* <p>
* All argument processor methods must be static, may not return any values, and
* may not throw any exceptions.
*/
@Documented
@Target (ElementType.TYPE)
@Retention (RetentionPolicy.CLASS)
public @interface ArgumentProcessor {
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* The Before annotation instructs DiSL to insert the snippet body before the
* marked region. The snippet will be invoked before the entry of the region.
*
* NOTE: This is only general contract. It depends on particular marker how the
* contract will be implemented.
*
* Marks DiSL snippet to be inserted before the marked code region. The snippet
* will be executed before entering the marked code region.
* <p>
* NOTE: This is a general contract. The actual implementation depends on the
* particular marker used with the snippet.
* <p>
* This annotation should be used with methods.
*
* The method should be static, not return any values and not throw any
* exceptions.
*
* Method argument can be StaticContext, DynamicContext, ClassContext and
* ArgumentProcessorContext.
* <p>
* The snippet method must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* Supported method argument types include {@link StaticContext},
* {@link DynamicContext}, {@link ClassContext}, and
* {@link ArgumentProcessorContext}.
*/
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.CLASS)
public @interface Before {
// NOTE if you want to change names, you need to change
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
/**
* Marker class defines a region where the snippet is applied.
* Marker class. Determines the region of code where to apply the snippet.
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Argument for the marker (as string).
*
* <p>
* Default value: ""
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Scope of the methods, where the snippet is applied.
*
* <p>
* @see ch.usi.dag.disl.scope package for more info about scoping language.
*
* <p>
* Default value: "*"
*/
String scope() default "*";
/**
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* Default value: Object.class - means none
* <p>
* Default value: void.class - means none
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* Determines snippet ordering. Smaller number indicates that snippet
* will be inlined closer to the marked code region.
* <p>
* Default value: 100
*/
int order() default 100;
/**
* Advanced option. You can in general disable dynamic bypass on snippets,
* that are not using any other class.
*
* NOTE Usage of dynamic bypass is determined by the underlying
* <p>
* NOTE: Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
*
* <p>
* Default value: true
*/
boolean dynamicBypass() default true;
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Marks guard validation method.
*
* Marks a guard method. Guard methods allow filtering the locations in program
* code where a snippet should be applied.
* <p>
* This annotation should be used with methods.
*
* Guard method should be static and state-less.
*
* Method argument can be Shadow, StaticContext, GuardContext and for
* ArgumentProcessor guard also ArgumentContext.
* <p>
* A guard method should be {@code static} and stateless.
* <p>
* Method argument can be {@link Shadow}, {@link StaticContext},
* {@link GuardContext} and for {@link ArgumentProcessor} guard also
* {@link ArgumentContext}.
*/
@Retention(RetentionPolicy.RUNTIME) // to resolve annotation using reflection
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.RUNTIME) // to resolve annotation using reflection
public @interface GuardMethod {
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Annotation used in ArgumentProcessor to guard specific methods.
*
* Annotation used in {@link ArgumentProcessor} to guard specific methods.
* <p>
* This annotation should be used with methods.
*/
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.CLASS)
public @interface Guarded {
// NOTE if you want to change names, you need to change
// NOTE if you want to change names, you need to change
// ProcessorParser.ProcMethodAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
/**
* The guard class defining if the processor method will be inlined or not.
*/
Class<? extends Object> guard();
Class <? extends Object> guard();
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
// TODO add tool that will look for Instrumentation annotation and create meta-data for jar
// http://stackoverflow.com/questions/3644069/java-6-annotation-processing-configuration-with-ant
/**
* This method denotes DiSL instrumentation class.
*
* Marks a class as a DiSL instrumentation class.
* <p>
* This annotation should be used with classes.
*/
@Documented
@Target (ElementType.TYPE)
@Retention (RetentionPolicy.CLASS)
public @interface Instrumentation {
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* If attached to the processor method, it allows to process:
* short, byte and boolean in int processor,
* byte and boolean in short processor,
* boolean in byte processor.
* Extends the set of primitive integer types (except {@code long}) accepted
* by an argument processor method:
* <ul>
* <li>for {@code int} argument processor, it allows to process also
* {@code short}, {@code byte}, and {@code boolean} types;
* <li>for {@code short} argument processor, it allows to process also
* {@code byte}, and {@code boolean} types.
* <li>for {@code byte} argument processor, it allows to process also
* {@code boolean} type.
* </ul>
*/
@Documented
@Target (ElementType.METHOD)
@Retention (RetentionPolicy.CLASS)
public @interface ProcessAlso {
// NOTE if you want to change names, you need to change
// TODO Consider support for {@code long} types.
// NOTE if you want to change names, you need to change
// ProcessorParser.ProcessAlsoAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
public enum Type {
BOOLEAN,
BYTE,
SHORT
BOOLEAN, BYTE, SHORT
}
Type[] types();
Type [] types();
}
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;