[FLINK-3002] Add Either type, EitherTypeInfo, and EitherSerializer to…

… the Java API

This closes apache#1371

docs/apis/programming_guide.md

@@ -1493,6 +1493,7 @@ There are six different categories of data types:
 4. **Regular Classes**
 5. **Values**
 6. **Hadoop Writables**
+7. **Special Types**
 
 #### Tuples and Case Classes
 
@@ -1651,6 +1652,12 @@ be altered, allowing programmers to reuse objects and take pressure off the garb
 You can use types that implement the `org.apache.hadoop.Writable` interface. The serialization logic
 defined in the `write()`and `readFields()` methods will be used for serialization.
 
+#### Special Types
+
+You can use special types, including Scala's `Either`, `Option`, and `Try`.
+The Java API has its own custom implementation of `Either`.
+Similarly to Scala's `Either`, it represents a value of one two possible types, *Left* or *Right*.
+`Either` can be useful for error handling or operators that need to output two different types of records.
 
 #### Type Erasure & Type Inference
 

flink-java/src/main/java/org/apache/flink/api/java/typeutils/Either.java

@@ -0,0 +1,147 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.api.java.typeutils;
+
+/**
+ * This type represents a value of one two possible types, Left or Right
+ * (a disjoint union), inspired by Scala's Either type.
+ *
+ * @param <L> the type of Left
+ * @param <R> the type of Right
+ */
+public abstract class Either<L, R> {
+
+ /**
+ * Create a Left value of Either
+ */
+ public static <L, R> Either<L, R> left(L value) {
+ return new Left<L, R>(value);
+ }
+
+ /**
+ * Create a Right value of Either
+ */
+ public static <L, R> Either<L, R> right(R value) {
+ return new Right<L, R>(value);
+ }
+
+ /**
+ * Retrieve the Left value of Either.
+ * @return the Left value
+ * @throws IllegalStateException if called on a Right
+ */
+ public abstract L left() throws IllegalStateException;
+
+ /**
+ * Retrieve the Right value of Either.
+ * @return the Right value
+ * @throws IllegalStateException if called on a Left
+ */
+ public abstract R right() throws IllegalStateException;
+
+ /**
+ * 
+ * @return true if this is a Left value, false if this is a Right value
+ */
+ public final boolean isLeft() {
+ return getClass() == Left.class;
+ }
+
+ /**
+ * 
+ * @return true if this is a Right value, false if this is a Left value
+ */
+ public final boolean isRight() {
+ return getClass() == Right.class;
+ }
+
+ private static class Left<L, R> extends Either<L, R> {
+ private final L value;
+
+ public Left(L value) {
+ this.value = java.util.Objects.requireNonNull(value);
+ }
+
+ @Override
+ public L left() {
+ return value;
+ }
+
+ @Override
+ public R right() {
+ throw new IllegalStateException("Cannot retrieve Right value on a Left");
+ }
+
+ @Override
+ public boolean equals(Object object) {
+ if (object instanceof Left<?, ?>) {
+ final Left<?, ?> other = (Left<?, ?>) object;
+ return value.equals(other.value);
+ }
+ return false;
+ }
+
+ @Override
+ public int hashCode() {
+ return value.hashCode();
+ }
+
+ @Override
+ public String toString() {
+ return "Left(" + value.toString() + ")";
+ }
+ }
+
+ private static class Right<L, R> extends Either<L, R> {
+ private final R value;
+
+ public Right(R value) {
+ this.value = java.util.Objects.requireNonNull(value);
+ }
+
+ @Override
+ public L left() {
+ throw new IllegalStateException("Cannot retrieve Left value on a Right");
+ }
+
+ @Override
+ public R right() {
+ return value;
+ }
+
+ @Override
+ public boolean equals(Object object) {
+ if (object instanceof Right<?, ?>) {
+ final Right<?, ?> other = (Right<?, ?>) object;
+ return value.equals(other.value);
+ }
+ return false;
+ }
+
+ @Override
+ public int hashCode() {
+ return value.hashCode();
+ }
+
+ @Override
+ public String toString() {
+ return "Right(" + value.toString() + ")";
+ }
+ }
+}

flink-java/src/main/java/org/apache/flink/api/java/typeutils/EitherTypeInfo.java

@@ -0,0 +1,111 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.api.java.typeutils;
+
+import org.apache.flink.api.common.ExecutionConfig;
+import org.apache.flink.api.common.typeinfo.TypeInformation;
+import org.apache.flink.api.common.typeutils.TypeSerializer;
+import org.apache.flink.api.java.typeutils.runtime.EitherSerializer;
+
+/**
+ * A {@link TypeInformation} for the {@link Either} type of the Java API.
+ *
+ * @param <L> the Left value type
+ * @param <R> the Right value type
+ */
+public class EitherTypeInfo<L, R> extends TypeInformation<Either<L, R>> {
+
+ private static final long serialVersionUID = 1L;
+
+ private final TypeInformation<L> leftType;
+
+ private final TypeInformation<R> rightType;
+
+ public EitherTypeInfo(TypeInformation<L> leftType,TypeInformation<R> rightType) {
+ this.leftType = leftType;
+ this.rightType = rightType;
+ }
+
+ @Override
+ public boolean isBasicType() {
+ return false;
+ }
+
+ @Override
+ public boolean isTupleType() {
+ return false;
+ }
+
+ @Override
+ public int getArity() {
+ return 1;
+ }
+
+ @Override
+ public int getTotalFields() {
+ return 1;
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public Class<Either<L, R>> getTypeClass() {
+ return (Class<Either<L, R>>) (Class<?>) Either.class;
+ }
+
+ @Override
+ public boolean isKeyType() {
+ return false;
+ }
+
+ @Override
+ public TypeSerializer<Either<L, R>> createSerializer(ExecutionConfig config) {
+ return new EitherSerializer<L, R>(leftType.createSerializer(config),
+ rightType.createSerializer(config));
+ }
+
+ @Override
+ public String toString() {
+ return "Either <" + leftType.toString() + ", " + rightType.toString() + ">";
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public boolean equals(Object obj) {
+ if (obj instanceof EitherTypeInfo) {
+ EitherTypeInfo<L, R> other = (EitherTypeInfo<L, R>) obj;
+
+ return other.canEqual(this) &&
+ leftType.equals(other.leftType) &&
+ rightType.equals(other.rightType);
+ } else {
+ return false;
+ }
+ }
+
+ @Override
+ public int hashCode() {
+ return 17 * leftType.hashCode() + rightType.hashCode();
+ }
+
+ @Override
+ public boolean canEqual(Object obj) {
+ return obj instanceof EitherTypeInfo;
+ }
+
+}