1 /* 2 * Copyright (C) 2011 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.base; 18 19 import static com.google.common.base.Preconditions.checkNotNull; 20 21 import com.google.common.annotations.Beta; 22 import com.google.common.annotations.GwtCompatible; 23 24 import java.io.Serializable; 25 import java.util.Iterator; 26 import java.util.Set; 27 28 import javax.annotation.Nullable; 29 30 /** 31 * An immutable object that may contain a non-null reference to another object. Each 32 * instance of this type either contains a non-null reference, or contains nothing (in 33 * which case we say that the reference is "absent"); it is never said to "contain {@code 34 * null}". 35 * 36 * <p>A non-null {@code Optional<T>} reference can be used as a replacement for a nullable 37 * {@code T} reference. It allows you to represent "a {@code T} that must be present" and 38 * a "a {@code T} that might be absent" as two distinct types in your program, which can 39 * aid clarity. 40 * 41 * <p>Some uses of this class include 42 * 43 * <ul> 44 * <li>As a method return type, as an alternative to returning {@code null} to indicate 45 * that no value was available 46 * <li>To distinguish between "unknown" (for example, not present in a map) and "known to 47 * have no value" (present in the map, with value {@code Optional.absent()}) 48 * <li>To wrap nullable references for storage in a collection that does not support 49 * {@code null} (though there are 50 * <a href="http://code.google.com/p/guava-libraries/wiki/LivingWithNullHostileCollections"> 51 * several other approaches to this</a> that should be considered first) 52 * </ul> 53 * 54 * <p>A common alternative to using this class is to find or create a suitable 55 * <a href="http://en.wikipedia.org/wiki/Null_Object_pattern">null object</a> for the 56 * type in question. 57 * 58 * <p>This class is not intended as a direct analogue of any existing "option" or "maybe" 59 * construct from other programming environments, though it may bear some similarities. 60 * 61 * <p>See the Guava User Guide article on <a 62 * href="http://code.google.com/p/guava-libraries/wiki/UsingAndAvoidingNullExplained#Optional"> 63 * using {@code Optional}</a>. 64 * 65 * @param <T> the type of instance that can be contained. {@code Optional} is naturally 66 * covariant on this type, so it is safe to cast an {@code Optional<T>} to {@code 67 * Optional<S>} for any supertype {@code S} of {@code T}. 68 * @author Kurt Alfred Kluever 69 * @author Kevin Bourrillion 70 * @since 10.0 71 */ 72 @GwtCompatible(serializable = true) 73 public abstract class Optional<T> implements Serializable { 74 /** 75 * Returns an {@code Optional} instance with no contained reference. 76 */ absent()77 public static <T> Optional<T> absent() { 78 return Absent.withType(); 79 } 80 81 /** 82 * Returns an {@code Optional} instance containing the given non-null reference. 83 */ of(T reference)84 public static <T> Optional<T> of(T reference) { 85 return new Present<T>(checkNotNull(reference)); 86 } 87 88 /** 89 * If {@code nullableReference} is non-null, returns an {@code Optional} instance containing that 90 * reference; otherwise returns {@link Optional#absent}. 91 */ fromNullable(@ullable T nullableReference)92 public static <T> Optional<T> fromNullable(@Nullable T nullableReference) { 93 return (nullableReference == null) 94 ? Optional.<T>absent() 95 : new Present<T>(nullableReference); 96 } 97 Optional()98 Optional() {} 99 100 /** 101 * Returns {@code true} if this holder contains a (non-null) instance. 102 */ isPresent()103 public abstract boolean isPresent(); 104 105 /** 106 * Returns the contained instance, which must be present. If the instance might be 107 * absent, use {@link #or(Object)} or {@link #orNull} instead. 108 * 109 * @throws IllegalStateException if the instance is absent ({@link #isPresent} returns 110 * {@code false}) 111 */ get()112 public abstract T get(); 113 114 /** 115 * Returns the contained instance if it is present; {@code defaultValue} otherwise. If 116 * no default value should be required because the instance is known to be present, use 117 * {@link #get()} instead. For a default value of {@code null}, use {@link #orNull}. 118 * 119 * <p>Note about generics: The signature {@code public T or(T defaultValue)} is overly 120 * restrictive. However, the ideal signature, {@code public <S super T> S or(S)}, is not legal 121 * Java. As a result, some sensible operations involving subtypes are compile errors: 122 * <pre> {@code 123 * 124 * Optional<Integer> optionalInt = getSomeOptionalInt(); 125 * Number value = optionalInt.or(0.5); // error 126 * 127 * FluentIterable<? extends Number> numbers = getSomeNumbers(); 128 * Optional<? extends Number> first = numbers.first(); 129 * Number value = first.or(0.5); // error}</pre> 130 * 131 * <p>As a workaround, it is always safe to cast an {@code Optional<? extends T>} to {@code 132 * Optional<T>}. Casting either of the above example {@code Optional} instances to {@code 133 * Optional<Number>} (where {@code Number} is the desired output type) solves the problem: 134 * <pre> {@code 135 * 136 * Optional<Number> optionalInt = (Optional) getSomeOptionalInt(); 137 * Number value = optionalInt.or(0.5); // fine 138 * 139 * FluentIterable<? extends Number> numbers = getSomeNumbers(); 140 * Optional<Number> first = (Optional) numbers.first(); 141 * Number value = first.or(0.5); // fine}</pre> 142 */ or(T defaultValue)143 public abstract T or(T defaultValue); 144 145 /** 146 * Returns this {@code Optional} if it has a value present; {@code secondChoice} 147 * otherwise. 148 */ or(Optional<? extends T> secondChoice)149 public abstract Optional<T> or(Optional<? extends T> secondChoice); 150 151 /** 152 * Returns the contained instance if it is present; {@code supplier.get()} otherwise. If the 153 * supplier returns {@code null}, a {@link NullPointerException} is thrown. 154 * 155 * @throws NullPointerException if the supplier returns {@code null} 156 */ 157 @Beta or(Supplier<? extends T> supplier)158 public abstract T or(Supplier<? extends T> supplier); 159 160 /** 161 * Returns the contained instance if it is present; {@code null} otherwise. If the 162 * instance is known to be present, use {@link #get()} instead. 163 */ 164 @Nullable orNull()165 public abstract T orNull(); 166 167 /** 168 * Returns an immutable singleton {@link Set} whose only element is the contained instance 169 * if it is present; an empty immutable {@link Set} otherwise. 170 * 171 * @since 11.0 172 */ asSet()173 public abstract Set<T> asSet(); 174 175 /** 176 * If the instance is present, it is transformed with the given {@link Function}; otherwise, 177 * {@link Optional#absent} is returned. If the function returns {@code null}, a 178 * {@link NullPointerException} is thrown. 179 * 180 * @throws NullPointerException if the function returns {@code null} 181 * 182 * @since 12.0 183 */ transform(Function<? super T, V> function)184 public abstract <V> Optional<V> transform(Function<? super T, V> function); 185 186 /** 187 * Returns {@code true} if {@code object} is an {@code Optional} instance, and either 188 * the contained references are {@linkplain Object#equals equal} to each other or both 189 * are absent. Note that {@code Optional} instances of differing parameterized types can 190 * be equal. 191 */ 192 @Override equals(@ullable Object object)193 public abstract boolean equals(@Nullable Object object); 194 195 /** 196 * Returns a hash code for this instance. 197 */ 198 @Override hashCode()199 public abstract int hashCode(); 200 201 /** 202 * Returns a string representation for this instance. The form of this string 203 * representation is unspecified. 204 */ 205 @Override toString()206 public abstract String toString(); 207 208 /** 209 * Returns the value of each present instance from the supplied {@code optionals}, in order, 210 * skipping over occurrences of {@link Optional#absent}. Iterators are unmodifiable and are 211 * evaluated lazily. 212 * 213 * @since 11.0 (generics widened in 13.0) 214 */ 215 @Beta presentInstances( final Iterable<? extends Optional<? extends T>> optionals)216 public static <T> Iterable<T> presentInstances( 217 final Iterable<? extends Optional<? extends T>> optionals) { 218 checkNotNull(optionals); 219 return new Iterable<T>() { 220 @Override 221 public Iterator<T> iterator() { 222 return new AbstractIterator<T>() { 223 private final Iterator<? extends Optional<? extends T>> iterator = 224 checkNotNull(optionals.iterator()); 225 226 @Override 227 protected T computeNext() { 228 while (iterator.hasNext()) { 229 Optional<? extends T> optional = iterator.next(); 230 if (optional.isPresent()) { 231 return optional.get(); 232 } 233 } 234 return endOfData(); 235 } 236 }; 237 } 238 }; 239 } 240 241 private static final long serialVersionUID = 0; 242 } 243