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