001package Torello.Java.JSON;
002
003import Torello.JavaDoc.StaticFunctional;
004import Torello.JavaDoc.LinkJavaSource;
005import Torello.JavaDoc.JDHeaderBackgroundImg;
006
007import Torello.Java.Function.IntIntTConsumer;
008
009import javax.json.Json;
010import javax.json.JsonArray;
011import javax.json.JsonString;
012import javax.json.JsonObject;
013
014import java.util.function.Consumer;
015import java.util.function.Function;
016
017/**
018 * Utilities for parsing Json Array's and sending the parsed values into a Java Consumer
019 * Functional-Interface.
020 * 
021 * <EMBED CLASS='external-html' DATA-FILE-ID=GLASS_FISH_NOTE>
022 * <EMBED CLASS='external-html' DATA-FILE-ID=RJA_INTO_CONS>
023 * <EMBED CLASS='external-html' DATA-FILE-ID=JSON_BINDING_NOTE>
024 *
025 * @see Json
026 * @see JsonArray
027 */
028@StaticFunctional
029@JDHeaderBackgroundImg(EmbedTagFileID="RJA_JDHBI_CONS")
030public class RJArrIntoConsumer
031{
032    private RJArrIntoConsumer() { }
033
034    /**
035     * Converts a {@link JsonArray} into a {@code Stream<T>}.  It is important to remember that
036     * the package {@code Torello.Java.JSON} does not attempt to generate Java-Type's or their
037     * Constructors.  The 'Type' of the {@code Stream<T>} that is returned by this method (the
038     * value of {@code 'T'}) must be an Object-Class that contains a Constructor that accepts a
039     * {@code JsonObject} as input.
040     * 
041     * <BR /><BR />This package does not perform the type of Auto-Type-Generation that is done by
042     * Lombok or Jackson.
043     * 
044     * @param <T> This is the 'type' of the array being built.  If there were a class, for example,
045     * named {@code 'Automobile'}, the value passed to parameter {@code 'returnClass'} would simply
046     * be {@code Automobile.class}.
047     * 
048     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of the class
049     * that has been specified by Type-Parameter {@code 'T'}
050     * 
051     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
052     * inserted into the output-array when error-cases occur while interpreting the array contents.
053     * 
054     * @param FLAGS Optional flags.  See {@link JFlag} for details.
055     * 
056     * @param consumerClass The {@code java.lang.Class} of the {@code Consumer}-Type
057     * currently being used.
058     */
059    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=1)
060    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
061    public static <T> void objArr(
062            final JsonArray     ja,
063            final T             defaultValue,
064            final int           FLAGS,
065            final Class<T>      consumerClass,
066            final Consumer<T>   c
067        )
068    {
069        ProcessJsonArray.objToJava(
070            ja,
071            // new SettingsRec<T, Void>
072            SETTINGS_REC_BUILDER.createForConsumers
073                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(consumerClass))
074        );
075    }
076
077    /**
078     * Idential to {@link #objArr(JsonArray, Object, int, Class, Consumer)}, except this
079     * method-overload variant allows a user to provide just about any Lambda-Function to produce
080     * the instance of {@code 'returnClass'}.  This alleviates the requirement to only build 
081     * objects which contain a constructor that accepts a {@link JsonObject}), and instead allows
082     * <B><I>any</I></B> object to be constructed, so long as a Builder-Lambda
083     * ({@code 'objBuilder'}) is provided
084     * 
085     * @param objBuilder This should be any Lambda-Functionthat accepts a {@link JsonObject}, and
086     * produces an instance of {@code Class<T>}.
087     */
088    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=2)
089    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
090    public static <T> void objArr(
091            final JsonArray                 ja,
092            final T                         defaultValue,
093            final int                       FLAGS,
094            final Function<JsonObject, T>   objBuilder,
095            final Class<T>                  consumerClass,
096            final Consumer<T>               c
097        )
098    {
099        ProcessJsonArray.objToJava(
100            ja,
101            // new SettingsRec<T, Void>
102            SETTINGS_REC_BUILDER.createForConsumers
103                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(objBuilder, consumerClass))
104        );
105    }
106
107    /**
108     * Iterates a {@link JsonArray} and passes the retrieved values to a User-Provided Consumer
109     * 
110     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of
111     * {@link JsonString}
112     * 
113     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
114     * inserted into the output-array when error cases occur at particular array-index locations.
115     * 
116     * @param FLAGS Optional flags.  See {@link JFlag} for details.
117     */
118    @LinkJavaSource(handle="BASIC_TYPES", name="STRING_REC")
119    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
120    public static void strArray(
121            final JsonArray         ja, 
122            final String            defaultValue,
123            final int               FLAGS,
124            final Consumer<String>  c
125        )
126    {
127        ProcessJsonArray.strToJava(
128            ja,
129            // new SettingsRec<String, Void>
130            SETTINGS_REC_BUILDER.createForConsumers
131                (defaultValue, FLAGS, null, c, BASIC_TYPES.STRING_REC())
132        );
133    }
134
135
136
137
138    // ********************************************************************************************
139    // ********************************************************************************************
140    // IntIntTConsumer Variant
141    // ********************************************************************************************
142    // ********************************************************************************************
143
144
145
146
147    /**
148     * Converts a {@link JsonArray} into a {@code Stream<T>}.  It is important to remember that
149     * the package {@code Torello.Java.JSON} does not attempt to generate Java-Type's or their
150     * Constructors.  The 'Type' of the {@code Stream<T>} that is returned by this method (the
151     * value of {@code 'T'}) must be an Object-Class that contains a Constructor that accepts a
152     * {@code JsonObject} as input.
153     * 
154     * <BR /><BR />This package does not perform the type of Auto-Type-Generation that is done by
155     * Lombok or Jackson.
156     * 
157     * @param <T> This is the 'type' of the array being built.  If there were a class, for example,
158     * named {@code 'Automobile'}, the value passed to parameter {@code 'returnClass'} would simply
159     * be {@code Automobile.class}.
160     * 
161     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of the class
162     * that has been specified by Type-Parameter {@code 'T'}
163     * 
164     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
165     * inserted into the output-array when error-cases occur while interpreting the array contents.
166     * 
167     * @param FLAGS Optional flags.  See {@link JFlag} for details.
168     * 
169     * @param consumerClass The {@code java.lang.Class} of the {@code IntIntTConsumer}-Type
170     * currently being used.
171     */
172    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=1)
173    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
174    public static <T> void objArr2(
175            final JsonArray             ja,
176            final T                     defaultValue,
177            final int                   FLAGS,
178            final Class<T>              consumerClass,
179            final IntIntTConsumer<T>    c
180        )
181    {
182        ProcessJsonArray.objToJava(
183            ja,
184            // new SettingsRec<T, Void>
185            SETTINGS_REC_BUILDER.createForIIConsumers
186                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(consumerClass))
187        );
188    }
189
190    /**
191     * Idential to {@link #objArr2(JsonArray, Object, int, Class, IntIntTConsumer)}, except this
192     * method-overload variant allows a user to provide just about any Lambda-Function to produce
193     * the instance of {@code 'returnClass'}.  This alleviates the requirement to only build 
194     * objects which contain a constructor that accepts a {@link JsonObject}), and instead allows
195     * <B><I>any</I></B> object to be constructed, so long as a Builder-Lambda
196     * ({@code 'objBuilder'}) is provided
197     * 
198     * @param objBuilder This should be any Lambda-Functionthat accepts a {@link JsonObject}, and
199     * produces an instance of {@code Class<T>}.
200     */
201    @LinkJavaSource(handle="BASIC_TYPES", name="OBJECT", paramCount=2)
202    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
203    public static <T> void objArr2(
204            final JsonArray                 ja,
205            final T                         defaultValue,
206            final int                       FLAGS,
207            final Function<JsonObject, T>   objBuilder,
208            final Class<T>                  consumerClass,
209            final IntIntTConsumer<T>        c
210        )
211    {
212        ProcessJsonArray.objToJava(
213            ja,
214            // new SettingsRec<T, Void>
215            SETTINGS_REC_BUILDER.createForIIConsumers
216                (defaultValue, FLAGS, null, c, BASIC_TYPES.OBJECT(objBuilder, consumerClass))
217        );
218    }
219
220    /**
221     * Iterates a {@link JsonArray} and passes the retrieved values to a User-Provided Consumer
222     * 
223     * @param ja Any {@code JsonArray}, but preferrably one which contains instances of
224     * {@link JsonString}
225     * 
226     * @param defaultValue When used in conjunction with {@code 'FLAGS'}, this default-value may be
227     * inserted into the output-array when error cases occur at particular array-index locations.
228     * 
229     * @param FLAGS Optional flags.  See {@link JFlag} for details.
230     */
231    @LinkJavaSource(handle="BASIC_TYPES", name="STRING_REC")
232    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="createForConsumers")
233    public static void strArray2(
234            final JsonArray                 ja, 
235            final String                    defaultValue,
236            final int                       FLAGS,
237            final IntIntTConsumer<String>   c
238        )
239    {
240        ProcessJsonArray.strToJava(
241            ja,
242            // new SettingsRec<String, Void>
243            SETTINGS_REC_BUILDER.createForIIConsumers
244                (defaultValue, FLAGS, null, c, BASIC_TYPES.STRING_REC())
245        );
246    }
247
248
249}