Maybe (Apache Brooklyn)

java.lang.Object
- org.apache.brooklyn.util.guava.Maybe<T>

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Maybe.Absent, Maybe.AbstractPresent, Maybe.SoftlyPresent
```
public abstract class Maybe<T>
extends java.lang.Object
implements java.io.Serializable
```
Like Guava Optional but permitting null and permitting errors to be thrown.

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Maybe.Absent<T>`
`static class`	`Maybe.AbsentNull<T>`
`static class`	`Maybe.AbstractPresent<T>`
`static class`	`Maybe.MaybeSupplier<T>`
`static class`	`Maybe.Present<T>`
`static class`	`Maybe.SoftlyPresent<T>`

Constructor Summary

Constructors
Constructor and Description

Maybe()

Constructors
Constructor and Description
`Maybe()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static <T> Maybe<T>`	`absent()` Returns an absent indicator.
`static <T> Maybe<T>`	`absent(<any> exceptionSupplier)` Creates an absent whose `get()` throws a `RuntimeException` generated on demand from the given supplier
`static <T> Maybe<T>`	`absent(java.lang.String message)` Convenience for `absentWithTrace(String)`.
`static <T> Maybe<T>`	`absent(java.lang.String message, java.lang.Throwable cause)` As `absent(Throwable)` but using the given message as the message on the `IllegalStateException` thrown if a user does a `get()`.
`static <T> Maybe<T>`	`absent(java.lang.Throwable cause)` As `absentWithTrace(String)` but using the provided exception instead of this location as the cause, and a string based on this cause as the message on the `IllegalStateException` thrown if a user does a `get()`.
`static <T> Maybe<T>`	`absentNoTrace(java.lang.String message)` Creates an absent whose get throws an `IllegalStateException` with the indicated message, but not a stack trace for the calling location.
`static <T> Maybe<T>`	`absentNull()` as `absentNull(String)` but with a generic message
`static <T> Maybe<T>`	`absentNull(java.lang.String message)` like `absent(String)` but `isNull()` will return true on the result.
`static <T> Maybe<T>`	`absentWithTrace(java.lang.String message)` Creates an absent whose `get()` throws an `IllegalStateException` with the indicated message.
`java.util.Set<T>`	`asSet()`
`static <T> Maybe<T>`	`cast(Maybe<? extends T> value)` Casts the given value to the desired type.
`boolean`	`equals(java.lang.Object obj)` Two `Maybe` instances are equal if both present wrapping the same value, or if both are absent for any reason.
`static <T> Maybe<T>`	`fromNullable(T value)` Creates a new Maybe object using `ofDisallowingNull(Object)` semantics.
`static <T> Maybe<T>`	`fromOptional(<any> value)` Creates a new Maybe object out of the `Optional` argument
`abstract T`	`get()`
`static java.lang.RuntimeException`	`getException(Maybe<?> t)` Finds the `Maybe.Absent.getException()` if `isAbsent()`, or null
`int`	`hashCode()`
`boolean`	`isAbsent()`
`boolean`	`isAbsentOrNull()`
`abstract boolean`	`isNull()` Whether the value is null, if present, or if it was specified as absent because it was null, e.g.
`abstract boolean`	`isPresent()`
`boolean`	`isPresentAndNonNull()`
`static <T> Maybe<T>`	`next(java.util.Iterator<T> iterator)` returns a Maybe containing the next element in the iterator, or absent if none
`static <T> Maybe<T>`	`of(<any> value)`
`static <T> Maybe<T>`	`of(<any> value)`
`static <T> Maybe<T>`	`of(T value)` Creates a new Maybe object.
`static <T> Maybe<T>`	`ofAllowingNull(T value)` Creates a new Maybe object which is present.
`static <T> Maybe<T>`	`ofDisallowingNull(T value)` Creates a new Maybe object which is present if and only if the argument is not null.
`T`	`or(<any> nextValue)`
`Maybe<T>`	`or(Maybe<T> nextValue)`
`T`	`or(T nextValue)`
`T`	`orNull()`
`T`	`orThrowUnwrapped()` As `get()` but if the Maybe wraps an exception (and where `get()` throws a `RuntimeException` indicating the caller, caused by the exception in original processing) this throws the original unwrapped exception (masking the caller's location)
`static <T> java.lang.Iterable<T>`	`presentInstances(java.lang.Iterable<? extends Maybe<? extends T>> maybes)` Returns the value of each present instance from the supplied `maybes`, in order, skipping over occurrences of `absent()`.
`static <T> Maybe<T>`	`soft(T value)` creates an instance wrapping a `SoftReference`, so it might go absent later on.
`static <T> Maybe<T>`	`softThen(T value, Maybe<T> ifEmpty)` creates an instance wrapping a `SoftReference`, using the second item given if the first argument is dereferenced.
`<any>`	`toOptional()` Converts the given `Maybe` to `Optional`, failing if this `Maybe` contains null.
`java.lang.String`	`toString()`
`<V> Maybe<V>`	`transform(<any> f)`

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Maybe
```
public Maybe()
```
- Method Detail
  - absent
```
public static <T> Maybe<T> absent()
```
    Returns an absent indicator. No message is available and access does not include any reference to this creation. Therefore it is fast and simple, but hard to work with if someone might get() it and want a useful exception. See also absentNoTrace(String) to include a message with very low overhead, or absentWithTrace(String) or absent(Throwable) for more control over the exception thrown.
  - absent
```
public static <T> Maybe<T> absent(java.lang.String message)
```
    Convenience for absentWithTrace(String).
  - absentWithTrace
```
public static <T> Maybe<T> absentWithTrace(java.lang.String message)
```
    Creates an absent whose get() throws an IllegalStateException with the indicated message. Both stack traces (the cause and the callers) are provided, which can be quite handy, but comparatively expensive as the cause stack trace has to generated when this method is invoked, even if it is never accessed. See also absentNoTrace(String) and absent(Throwable).
  - absentNoTrace
```
public static <T> Maybe<T> absentNoTrace(java.lang.String message)
```
    Creates an absent whose get throws an IllegalStateException with the indicated message, but not a stack trace for the calling location. As stack traces can be comparatively expensive this is useful for efficiency, but it can make debugging harder as the origin of the absence is not kept, in contrast to absentWithTrace(String) and absent(Throwable).
  - absent
```
public static <T> Maybe<T> absent(java.lang.Throwable cause)
```
    As absentWithTrace(String) but using the provided exception instead of this location as the cause, and a string based on this cause as the message on the IllegalStateException thrown if a user does a get(). Useful if an Exception has already been generated (and no overhead) or if you want to supply a specific cause as in absent(new MyException(...)) (but there is the Exception creation overhead there).
  - absent
```
public static <T> Maybe<T> absent(java.lang.String message,
                                  java.lang.Throwable cause)
```
    As absent(Throwable) but using the given message as the message on the IllegalStateException thrown if a user does a get().
  - absent
```
public static <T> Maybe<T> absent(<any> exceptionSupplier)
```
    Creates an absent whose get() throws a RuntimeException generated on demand from the given supplier
  - absentNull
```
public static <T> Maybe<T> absentNull()
```
    as absentNull(String) but with a generic message
  - absentNull
```
public static <T> Maybe<T> absentNull(java.lang.String message)
```
    like absent(String) but isNull() will return true on the result.
  - ofAllowingNull
```
public static <T> Maybe<T> ofAllowingNull(@Nullable
                                          T value)
```
    Creates a new Maybe object which is present. The argument may be null and the object still present, which may be confusing in some contexts (traditional Optional usages) but may be natural in others (where null is a valid value, distinguished from no value set). See also ofDisallowingNull(Object).
  - ofDisallowingNull
```
public static <T> Maybe<T> ofDisallowingNull(@Nullable
                                             T value)
```
    Creates a new Maybe object which is present if and only if the argument is not null. If the argument is null, then an absentNull() is returned, on which isNull() will be true.
  - of
```
public static <T> Maybe<T> of(@Nullable
                              T value)
```
    Creates a new Maybe object. Currently this uses ofAllowingNull(Object) semantics, but it is recommended to use that method for clarity if the argument might be null.
  - cast
```
public static <T> Maybe<T> cast(Maybe<? extends T> value)
```
    Casts the given value to the desired type. This is valid because Maybe is immutable, so things like Maybe<Object> is a super-type of Maybe<String>.
  - toOptional
```
public <any> toOptional()
```
    Converts the given Maybe to Optional, failing if this Maybe contains null.
  - fromNullable
```
public static <T> Maybe<T> fromNullable(@Nullable
                                        T value)
```
    Creates a new Maybe object using ofDisallowingNull(Object) semantics. It is recommended to use that method for clarity. This method is provided for consistency with Optional#fromNullable(Object).
  - fromOptional
```
public static <T> Maybe<T> fromOptional(<any> value)
```
    Creates a new Maybe object out of the Optional argument
  - soft
```
public static <T> Maybe<T> soft(@Nonnull
                                T value)
```
    creates an instance wrapping a SoftReference, so it might go absent later on. if null is supplied the result is a present null.
  - softThen
```
public static <T> Maybe<T> softThen(T value,
                                    Maybe<T> ifEmpty)
```
    creates an instance wrapping a SoftReference, using the second item given if the first argument is dereferenced. however if the first argument is null, this is a permanent present null, as of(Object) with null.
  - of
```
public static <T> Maybe<T> of(<any> value)
```
  - of
```
public static <T> Maybe<T> of(<any> value)
```
  - next
```
public static <T> Maybe<T> next(java.util.Iterator<T> iterator)
```
    returns a Maybe containing the next element in the iterator, or absent if none
  - isPresent
```
public abstract boolean isPresent()
```
  - get
```
public abstract T get()
```
  - isAbsent
```
public boolean isAbsent()
```
  - isAbsentOrNull
```
public boolean isAbsentOrNull()
```
  - isPresentAndNonNull
```
public boolean isPresentAndNonNull()
```
  - isNull
```
public abstract boolean isNull()
```
    Whether the value is null, if present, or if it was specified as absent because it was null, e.g. using fromNullable(Object).
  - or
```
public T or(T nextValue)
```
  - or
```
public Maybe<T> or(Maybe<T> nextValue)
```
  - or
```
public T or(<any> nextValue)
```
  - orNull
```
public T orNull()
```
  - orThrowUnwrapped
```
public T orThrowUnwrapped()
```
    As get() but if the Maybe wraps an exception (and where get() throws a RuntimeException indicating the caller, caused by the exception in original processing) this throws the original unwrapped exception (masking the caller's location)
    As this masks the caller's exception, use with care, typically in a location near the original execution, otherwise it can get confusing. For instance someCallReturningMaybe().orThrowUnwrapped() is a nice idiom, but someMaybeVarReturnedEarlier.orThrowUnwrapped() is usually a bad idea.
    The benefit of this is simpler stack traces and preservation of original exception type.
  - asSet
```
public java.util.Set<T> asSet()
```
  - transform
```
public <V> Maybe<V> transform(<any> f)
```
  - presentInstances
```
public static <T> java.lang.Iterable<T> presentInstances(java.lang.Iterable<? extends Maybe<? extends T>> maybes)
```
    Returns the value of each present instance from the supplied maybes, in order, skipping over occurrences of absent(). Iterators are unmodifiable and are evaluated lazily.
    
    See Also:
    
    Optional#presentInstances(Iterable)
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Two Maybe instances are equal if both present wrapping the same value, or if both are absent for any reason.
    Specifically, in cases of absences, the reasons for absence are not compared. This could be revisited if there is compelling reason to do so, but in the main the cause of an absence is interesting for giving information to the user. Note this is different to the behaviour of Optional which says absences are only equal if they are the same instance.
    
    Overrides:
    
    equals in class java.lang.Object
  - getException
```
public static java.lang.RuntimeException getException(Maybe<?> t)
```
    Finds the Maybe.Absent.getException() if isAbsent(), or null

Class Maybe<T>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Maybe

Method Detail

absent

absent

absentWithTrace

absentNoTrace

absent

absent

absent

absentNull

absentNull

ofAllowingNull

ofDisallowingNull

of

cast

toOptional

fromNullable

fromOptional

soft

softThen

of

of

next

isPresent

get

isAbsent

isAbsentOrNull

isPresentAndNonNull

isNull

or

or

or

orNull

orThrowUnwrapped

asSet

transform

presentInstances

toString

hashCode

equals

getException