org.apache.flink.api.java.functions

Class FunctionAnnotation

java.lang.Object

org.apache.flink.api.java.functions.FunctionAnnotation

@Public
public class FunctionAnnotation
extends Object

This class defines Java annotations for semantic assertions that can be added to Flink functions. Semantic annotations can help the Flink optimizer to generate more efficient execution plans for Flink programs. For example, a ForwardedFields assertion for a map-type function can be declared as:

 {@literal @}ForwardedFields({"f0; f2->f1"})
 public class MyMapper extends MapFunction<Tuple3<String, String, Integer>, Tuple3<String, Integer, Integer>>
 {
     public Tuple3<String, Integer, Integer> map(Tuple3<String, String, Integer> val) {

         return new Tuple3<String, Integer, Integer>(val.f0, val.f2, 1);
     }
 }
 

All annotations take Strings with expressions that refer to (nested) value fields of the input and output types of a function. Field expressions for of composite data types (tuples, POJOs, Scala case classes) can be expressed in different ways, depending on the data type they refer to.

• Java tuple data types (such as Tuple3): A tuple field can be addressed using its 0-offset index or name, e.g., the second field of a Java tuple is addressed by "1" or "f1".
• Java POJO data types: A POJO field is addressed using its names, e.g., "xValue" for the member field xValue of a POJO type that describes a 2d-coordinate.
• Scala tuple data types (such as scala.Tuple3): A tuple field can be addressed using its 1-offset name (following Scala conventions) or 0-offset index, e.g., the second field of a Scala tuple is addressed by "_2" or 1
• Scala case classes: A case class field is addressed using its names, e.g., "xValue" for the field xValue of a case class that describes a 2d-coordinate.

Nested fields are addressed by navigation, e.g., "f1.xValue" addresses the field xValue of a POJO type, that is stored at the second field of a Java tuple. In order to refer to all fields of a composite type (or the composite type itself) such as a tuple, POJO, or case class type, a "*" wildcard can be used, e.g., f2.* or f2 reference all fields of a composite type at the third position of a Java tuple.

NOTE: The use of semantic annotation is optional! If used correctly, semantic annotations can help the Flink optimizer to generate more efficient execution plans. However, incorrect semantic annotations can cause the optimizer to generate incorrect execution plans which compute wrong results! So be careful when adding semantic annotations.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FunctionAnnotation.ForwardedFields The ForwardedFields annotation declares fields which are never modified by the annotated function and which are forwarded at the same position to the output or unchanged copied to another position in the output.
static interface	FunctionAnnotation.ForwardedFieldsFirst The ForwardedFieldsFirst annotation declares fields of the first input of a function which are never modified by the annotated function and which are forwarded at the same position to the output or unchanged copied to another position in the output.
static interface	FunctionAnnotation.ForwardedFieldsSecond The ForwardedFieldsSecond annotation declares fields of the second input of a function which are never modified by the annotated function and which are forwarded at the same position to the output or unchanged copied to another position in the output.
static interface	FunctionAnnotation.NonForwardedFields The NonForwardedFields annotation declares ALL fields which not preserved on the same position in a functions output.
static interface	FunctionAnnotation.NonForwardedFieldsFirst The NonForwardedFieldsFirst annotation declares for a function ALL fields of its first input which are not preserved on the same position in its output.
static interface	FunctionAnnotation.NonForwardedFieldsSecond The NonForwardedFieldsSecond annotation declares for a function ALL fields of its second input which are not preserved on the same position in its output.
static interface	FunctionAnnotation.ReadFields The ReadFields annotation declares for a function all fields which it accesses and evaluates, i.e., all fields that are used by the function to compute its result.
static interface	FunctionAnnotation.ReadFieldsFirst The ReadFieldsFirst annotation declares for a function all fields of the first input which it accesses and evaluates, i.e., all fields of the first input that are used by the function to compute its result.
static interface	FunctionAnnotation.ReadFieldsSecond The ReadFieldsSecond annotation declares for a function all fields of the second input which it accesses and evaluates, i.e., all fields of the second input that are used by the function to compute its result.

Method Summary

Modifier and Type	Method and Description
static Set<Annotation>	readDualForwardAnnotations(Class<?> udfClass) Reads the annotations of a user defined function with two inputs and returns semantic properties according to the forwarded fields annotated.
static Set<Annotation>	readSingleForwardAnnotations(Class<?> udfClass) Reads the annotations of a user defined function with one input and returns semantic properties according to the forwarded fields annotated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

readSingleForwardAnnotations

@Internal
public static Set<Annotation> readSingleForwardAnnotations(Class<?> udfClass)

Reads the annotations of a user defined function with one input and returns semantic properties according to the forwarded fields annotated.

Parameters:

udfClass - The user defined function, represented by its class.

Returns:

The DualInputSemanticProperties containing the forwarded fields.

readDualForwardAnnotations

@Internal
public static Set<Annotation> readDualForwardAnnotations(Class<?> udfClass)

Reads the annotations of a user defined function with two inputs and returns semantic properties according to the forwarded fields annotated.

Parameters:

udfClass - The user defined function, represented by its class.

Returns:

The DualInputSemanticProperties containing the forwarded fields.