001package Torello.Java.Additional;
002
003import java.lang.reflect.InvocationTargetException;
004
005/**
006 * <CODE>VarList&lt;A, B&gt; - Documentation</CODE><BR /><BR />
007 * <EMBED CLASS="external-html" DATA-FILE-ID="VARLIST">
008 */
009public interface VarList<A, B>
010{
011    /**
012     * This returns a {@code 'new'} instance of {@code 'this' VarList} interface.
013     * @return An instance of the invoking {@code VarList<A, B>}.  It is expected any internal information,
014     * such as transforms or sorts be preserved.
015     */
016    public      VarList<A, B>   create();
017
018    /**
019     * This will also return a {@code 'new'} instance of {@code 'this' VarList} interface.
020     * The difference shall be that as elements are inserted/received by the implementing software, these
021     * new elements will be placed in the list-type {@code A 'a'}.
022     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN> Instances of {@code VarList} that
023     * attempt to return {@code array's, Stream's}, or {@code Iterator's} are not compatible with this
024     * interface method.  If attempting to use this {@code 'appendTo'} method with an {@code array,
025     * Stream}, or {@code Iterator} - then an {@code 'UnsupportedOperationException'} shall throw.
026     * <BR /><BR />Primarily, attempting to "concatenate" to one of these data-structures would generally
027     * require a new instance - <I><B>and a new pointer reference</I></B>.  Since instantiating a new
028     * array is not consistent with the idea of "concatenation," this method shall simply throw this 
029     * exception, since the pointer array-reference returned would not be the same as the one provided
030     * as a parameter here.
031     * @param a This may be any instance of the desired output return type.  If {@code 'this'} instance
032     * of {@code VarList} were a {@code VarList<Vector<String>, String>>}, then one could provide a 
033     * {@code Vector<String>} to this method, and list-elements would be appended to the end of the 
034     * {@code Vector 'a'}, rather than being inserted into a new {@code 'Vector'} instance.
035     * @return This shall return a new instance of {@code 'VarList'}, where all elements that provided
036     * for insertion into this list shall be inserted into {@code 'a'}, rather than into a newly
037     * instantiated list.
038     * @throws OperationUnsupportedException If parametrized-type {@code 'A'} is an instance of
039     * {@code array, Stream}, or {@code Iterator}, then this exception shall throw.
040     */
041    public      VarList<A, B>   appendTo(A a);
042
043    /**
044     * This method must accept a new element into the internally stored list.
045     * @param b The node or element being inserted into this {@code VarList}
046     */
047    public      void            insert(B b);
048
049    /**
050     * This must retrieve or return the internally stored list.
051     * @return The internally stored list.
052     */
053    public      A               retrieve();
054
055    static void throwUOE(String type) throws UnsupportedOperationException
056    {
057        throw new UnsupportedOperationException(
058            "You have attempted an append operation to a data-type whose reference cannot be " +
059            "extended using the Standard Java Memory Model.  Requested append to type: " +
060            "[" + type + "] isn't possible.  " +
061            "All attempts to append to an array, stream, or iterator shall result in this " +
062            "exception throw.  To append to an array, stream, or iterator: use the " +
063            "VarList<Stream.Builder, T>, and then build the stream.  Afterwards use " +
064            "Stream.iterator(), Stream.toArray(), or the Stream itself."
065        );
066    }
067
068    static void throwUOE2() throws UnsupportedOperationException
069    {
070        throw new UnsupportedOperationException(
071            "You may not use the append operation with Sort Then Apply.  The sort-information is " +
072            "lost after an apply operation."
073        );
074    }
075}