Skip to main content
summaryrefslogtreecommitdiffstats
blob: 09a517520d497f7c749ddc531a6071b8f8449289 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
/******************************************************************************
 * Copyright (c) David Orme and others
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    David Orme - initial API and implementation
 ******************************************************************************/
package org.eclipse.e4.core.functionalprog.optionmonad;

import org.eclipse.core.runtime.IStatus;

/**
 * A Java implementation of the "Option Monad" design pattern.  (Note that this
 * particular implementation isn't actually a full monad, but for our purposes
 * it doesn't matter.)  This is inspired by the following blog:
 * http://www.codecommit.com/blog/scala/the-option-pattern and also 
 * Functional Java (http://www.functionaljava.org)'s Option implementation.
 * <p>
 * The Option pattern provides a unified method for coding functions that could
 * return Some<T>(value) or also might fail to produce a value, and thus return
 * None<T>.
 * <p>
 * This pattern makes explicit that a method might not return a value, eliminating
 * guesswork about if the method might return null when reading/learning APIs.
 *
 * @param <T> The type the Option encapsulates
 */
public interface Option<T> {
    /**
     * Return the value inside the Option, or throw an UnsupportedOperationException
     * if there is no value.
     * 
     * @return the encapsulated T or throw UnsupportedOperationException if empty
     */
    public T get();
    
    /**
     * Return the encapsulated instance of T, if there is one, or alternatively
     * return the defaultValue if there is no encapsulated T.
     * 
     * @param defaultValue The default value to return if there is no T in the 
     * container.
     * 
     * @return the encapsulated instance of T, if there is one, or alternatively
     * return the defaultValue if there is no encapsulated T.
     */
    public T getOrSubstitute(T defaultValue);
    
    /**
     * Return the encapsulated instance of T, if there is one.  If the 
     * container is empty, throw the passed exception.
     * 
     * @param <E> The type of exception to throw.
     * @param exception The exception to throw.
     * @return the encapsulated instance of T, if there is one.  If the 
     * container is empty, throw the passed exception.
     * @throws E The exception type that could be thrown.
     */
    public <E extends Throwable> T getOrThrow(E exception) throws E;
    
    /**
     * Return true if this Option contains a value or false if it is empty.
     * 
     * @return true if this Option contains a value or false if it is empty.
     */
    public boolean hasValue();
    
    /**
     * Returns an IStatus providing further information on this result.  If
     * clients do not explicitly provide an IStatus result, then Some(value) 
     * will return Status.OK_STATUS and None will return Status.CANCEL_STATUS.
     * Alternatively, clients can supply their own IStatus to return along with
     * Some(value) or None.
     * 
     * @return IStatus additional information on this operation.
     */
    public IStatus getStatus();
}
 

Back to the top