Interface VarList<LIST,​CONTENTS>

  • Type Parameters:
    LIST - This is the 'type' that the user would like returned from the method call. This type must be some type of container such as a list, collection, stream or possibly an array.

    AN ASIDE: In classes that reside within the JDK, Generic Type-Parameters are almost always named using a singl-letter, such as T, U, V, R etc... This choice by Oracle is not actually required, and a Type Parameter is allowed to use several characters (upper or lower case), and even numbers. The standard naming conventions don't exactly apply here since this parameterized type represens a 'List' or 'Container' - for which there are no standardized Oracle Naming Conventions!

    FINALLY: 'LIST' will, in almost all cases, itself have generic-type parameters of its own. For example, if Type-Parameter 'LIST' were computed to be a Stream<FileNode>, or possibly a Stream<String>, the fact that 'LIST', itself, also is a Java Generic is perfectly acceptable the Java Compiler's Type-Inference Logic.
    CONTENTS - This is the 'type' of the original data-structure (before any potential 'tranformations'). For instance, in the case of class FileNode and FileNode.RetTypeChoice, this shall always be type FileNode.

    NOTE: Unless a transformer is applied using one of the two 'WithApply' VarListBuilder's, the 'CONTENTS' type will be the type that the container is holding.
    public interface VarList<LIST,​CONTENTS>
    Implementation of the FileNode class 'RetTypeChoice'.

    Java HTML Library Helper for Torello.Java.FileNode

    Currently, the only application for the VarList User-Specified Variable Return Type Interface is for the FileNode helper-class 'RetTypeChoice'.

    This class could theoretically be used wherever there are many container-variants for the same set of identical-data being returned to a user.
    Allows a return of different list & collection implementations from a single method.


    • Method Detail

      • create

        🡇  ⇈  ⮫ 
        VarList<LIST,​CONTENTS> create()
        This returns a 'new' instance of 'this' VarList interface.
        Returns:
        An instance of the invoking VarList<LIST, CONTENTS>. It is expected that any internal information required, such as transforms or sorts, be preserved.

      • appendTo

        🡅  🡇  ⇈  ⮫ 
        VarList<LIST,​CONTENTS> appendTo​(LIST list)
        This will also return create a 'new' instance of 'this' VarList interface. The difference shall be that as elements are inserted/received by the implementing software, these new elements will be placed into the list passed to parameter 'list'.

        IMPORTANT: Instances of VarList that attempt to return array's, Stream's, or Iterator's are not compatible with this interface method, and an 'UnsupportedOperationException' shall throw. This is because Java's syntax does not provide a simple way to extend the length of array's, Stream's, or Iterator's.
        Parameters:
        list - This may be any instance of the desired output return type. If 'this' instance of VarList were a VarList<Vector<String>, String>>, then one could provide a Vector<String> to this method, and the ultimate effect this would have is that list-elements would be appended into Vector 'list', rather than being added to a new 'Vector' instance.
        Returns:
        This shall return a new instance of 'VarList', where all elements that were provided to the builder for insertion, shall be inserted into 'list', rather than into a newly instantiated list.
        Throws:
        OperationUnsupportedException - If parametrized-type 'LIST' is an instance of array, Stream, or Iterator, then this exception shall throw.

      • insert

        🡅  🡇  ⇈  ⮫ 
        void insert​(CONTENTS contents)
        This method must accept a new element into the internally stored list.
        Parameters:
        contents - The node or element being inserted into this VarList

      • retrieve

        🡅  🡇  ⇈  ⮫ 
        LIST retrieve()
        This must retrieve or return the internally stored list.
        Returns:
        The internally stored list.

      • throwUOE

        🡅  🡇  ⇈  ⮫ 
        static void throwUOE​(java.lang.String type)
              throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
        Code:
        Exact Method Body:
         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 being throwmn.  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."
 );

      • throwUOE2

        🡅  ⇈  ⮫ 
        static void throwUOE2()
               throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
        Code:
        Exact Method Body:
         throw new UnsupportedOperationException(
     "You may not use the append operation with Sort-Then-Apply.  The sort-information is " +
     "lost after an apply operation."
 );