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
package Torello.Java.Additional;

import java.lang.reflect.InvocationTargetException;

/**
 * <CODE>VarList&lt;A, B&gt; - Documentation</CODE><BR /><BR />
 * <EMBED CLASS="external-html" DATA-FILE-ID="VARLIST">
 */
public interface VarList<A, B>
{
    /**
     * This returns a {@code 'new'} instance of {@code 'this' VarList} interface.
     * @return An instance of the invoking {@code VarList<A, B>}.  It is expected any internal information,
     * such as transforms or sorts be preserved.
     */
    public      VarList<A, B>   create();

    /**
     * This will also return a {@code 'new'} instance of {@code 'this' VarList} interface.
     * The difference shall be that as elements are inserted/received by the implementing software, these
     * new elements will be placed in the list-type {@code A 'a'}.
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN> Instances of {@code VarList} that
     * attempt to return {@code array's, Stream's}, or {@code Iterator's} are not compatible with this
     * interface method.  If attempting to use this {@code 'appendTo'} method with an {@code array,
     * Stream}, or {@code Iterator} - then an {@code 'UnsupportedOperationException'} shall throw.
     * <BR /><BR />Primarily, attempting to "concatenate" to one of these data-structures would generally
     * require a new instance - <I><B>and a new pointer reference</I></B>.  Since instantiating a new
     * array is not consistent with the idea of "concatenation," this method shall simply throw this 
     * exception, since the pointer array-reference returned would not be the same as the one provided
     * as a parameter here.
     * @param a This may be any instance of the desired output return type.  If {@code 'this'} instance
     * of {@code VarList} were a {@code VarList<Vector<String>, String>>}, then one could provide a 
     * {@code Vector<String>} to this method, and list-elements would be appended to the end of the 
     * {@code Vector 'a'}, rather than being inserted into a new {@code 'Vector'} instance.
     * @return This shall return a new instance of {@code 'VarList'}, where all elements that provided
     * for insertion into this list shall be inserted into {@code 'a'}, rather than into a newly
     * instantiated list.
     * @throws OperationUnsupportedException If parametrized-type {@code 'A'} is an instance of
     * {@code array, Stream}, or {@code Iterator}, then this exception shall throw.
     */
    public      VarList<A, B>   appendTo(A a);

    /**
     * This method must accept a new element into the internally stored list.
     * @param b The node or element being inserted into this {@code VarList}
     */
    public      void            insert(B b);

    /**
     * This must retrieve or return the internally stored list.
     * @return The internally stored list.
     */
    public      A               retrieve();

    static void throwUOE(String type) throws UnsupportedOperationException
    {
        throw new UnsupportedOperationException(
            "You have attempted an append operation to a data-type whose reference cannot be " +
            "extended using the Standard Java Memory Model.  Requested append to type: " +
            "[" + type + "] isn't possible.  " +
            "All attempts to append to an array, stream, or iterator shall result in this " +
            "exception throw.  To append to an array, stream, or iterator: use the " +
            "VarList<Stream.Builder, T>, and then build the stream.  Afterwards use " +
            "Stream.iterator(), Stream.toArray(), or the Stream itself."
        );
    }

    static void throwUOE2() throws UnsupportedOperationException
    {
        throw new UnsupportedOperationException(
            "You may not use the append operation with Sort Then Apply.  The sort-information is " +
            "lost after an apply operation."
        );
    }
}