001package Torello.Java;
002
003import java.io.*;
004import java.util.*;
005import java.util.stream.Stream;
006
007/**
008 * This class wraps the Google Cloud command-line tool <CODE><B>'gsutil'</B></CODE>, simply using
009 * the standard Java <CODE>java&#46;lang&#46;Process</CODE> object (in addition to Java HTML's
010 * <CODE>OSResponse</CODE>) thereby providing a simple Java-API for these operating-system calls.
011 * 
012 * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL>
013 * <EMBED ClASS='external-html' DATA-FILE-ID=OSC_WORA>
014 * <EMBED CLASS='external-html' DATA-CLASS=GSUTIL DATA-VAR=gsutil DATA-FILE-ID=OSC_ALL_FIELDS>
015 * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
016 *
017 * <!--
018 *  <EMBED CLASS="external html cannot ad this!" DATA-FILE-ID= NO! OSC_WILD_CARD_02> 
019 *  This class has a note about wild-cards built into GSUTIL
020 * -->
021 * 
022 * @see OSCommands
023 * @see OSResponse
024 */
025@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="OSC_INHERITORS")
026public class GSUTIL extends OSCommands implements Cloneable
027{
028    // Random character string.  It will only check the pointers anyway (not the string itself)
029    private static final String NO_TARGET = "?\t-$\n-ZZzz";
030
031
032    // ********************************************************************************************
033    // ********************************************************************************************
034    // Constructors
035    // ********************************************************************************************
036    // ********************************************************************************************
037
038
039    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_1> */
040    public GSUTIL() { super(); }
041
042    /**
043     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_2>
044     * @param outputAppendable <EMBED CLASS='external-html' DATA-FILE-ID=OSC_APPENDABLE_PARAM>
045     * @see OSCommands#outputAppendable
046     */
047    public GSUTIL(Appendable outputAppendable)
048    { super(outputAppendable); }
049
050    /**
051     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_3>
052     * 
053     * @param outputAppendable      <EMBED CLASS='external-html' DATA-FILE-ID=OSC_APPENDABLE_PARAM>
054     * @param commandStrAppendable  <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CSA_PARAM>
055     * @param standardOutput        <EMBED CLASS='external-html' DATA-FILE-ID=OSC_STND_OUT_PARAM>
056     * @param errorOutput           <EMBED CLASS='external-html' DATA-FILE-ID=OSC_ERROR_OUT_PARAM>
057     * @see OSCommands#outputAppendable
058     * @see OSCommands#commandStrAppendable
059     * @see OSCommands#standardOutput 
060     * @see OSCommands#errorOutput 
061     */
062    public GSUTIL(
063            Appendable outputAppendable,
064            Appendable commandStrAppendable,
065            Appendable standardOutput,
066            Appendable errorOutput
067        )
068    { super(outputAppendable, commandStrAppendable, standardOutput, errorOutput); }
069
070    /**
071     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_4>
072     * 
073     * @param standardOutput    <EMBED CLASS='external-html' DATA-FILE-ID=OSC_STND_OUT_PARAM>
074     * @param errorOutput       <EMBED CLASS='external-html' DATA-FILE-ID=OSC_ERROR_OUT_PARAM>
075     * @see OSCommands#standardOutput 
076     * @see OSCommands#errorOutput 
077     */
078    public GSUTIL(Appendable standardOutput, Appendable errorOutput)
079    { super(standardOutput, errorOutput); }
080
081    /**
082     * Used by the method {@code clone()}.
083     * @param other Another instance of this class.
084     */
085    protected GSUTIL(GSUTIL other) { super(other); }
086
087    /** {@inheritDoc} */
088    public GSUTIL clone() { return new GSUTIL(this); }
089
090
091    // ********************************************************************************************
092    // ********************************************************************************************
093    // GSUTIL RM
094    // ********************************************************************************************
095    // ********************************************************************************************
096
097
098    /**
099     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_RM>
100     * 
101     * @param s The GCS bucket-storage address of files to delete.  <B><I>Can Include</I></B>
102     * wildcards: {@code '*'} and {@code '**'}
103     * 
104     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'}
105     * with switches.
106     * 
107     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
108     * @throws IOException If there are any problems while invoking the operating-system command
109     * @see OSCommands#printAndRun(String[])
110     */
111    public OSResponse RM(String s, String... switches) throws IOException
112    {
113        String[] command = BUILD_COMMAND
114            (new String[] { "gsutil", "-m", "rm" }, switches, s, NO_TARGET);
115
116        return printAndRun(command);
117    }
118
119    /**
120     * Convenience Method.
121     * <BR />Invokes: {@link #RM(String[], String[])}
122     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
123     */
124    public OSResponse RM(Iterable<String> iterable, String... switches) throws IOException
125    { return RM(TO_ARRAY(iterable), switches); }
126
127    /**
128     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_RM>
129     * 
130     * @param sArr The list GCS bucket-storage address of files to delete.  <B><I>Can
131     * Include</I></B> wildcards: {@code '*'} and {@code '**'}
132     * 
133     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'} with
134     * switches.
135     * 
136     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
137     * @throws IOException If there are any problems while invoking the operating-system command
138     * @see OSCommands#printAndRun(String[])
139     */
140    public OSResponse RM(String[] sArr, String... switches) throws IOException
141    {
142        String[] command = BUILD_COMMAND
143            (new String[] { "gsutil", "-m", "rm" }, switches, sArr, NO_TARGET);
144
145        return printAndRun(command);
146    }
147
148
149    // ********************************************************************************************
150    // ********************************************************************************************
151    // GSUTIL MV
152    // ********************************************************************************************
153    // ********************************************************************************************
154
155
156    /**
157     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_MV>
158     * 
159     * @param source The GCS bucket-storage source-address.  <B><I>Can Include</I></B> wildcards:
160     * {@code '*'} and {@code '**'}
161     * 
162     * @param target The GCS bucket-storage target-address.
163     * 
164     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'}
165     * with switches.
166     * 
167     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
168     * @throws IOException If there are any problems while invoking the operating-system command
169     * @see OSCommands#printAndRun(String[])
170     */
171    public OSResponse MV(String source, String target, String... switches)
172        throws IOException
173    {
174        String[] command = BUILD_COMMAND
175            (new String[] { "gsutil", "-m", "mv" }, switches, source, target);
176
177        return printAndRun(command);
178    }   
179
180    /**
181     * Convenience Method.
182     * <BR />Invokes: {@link #MV(String[], String, String[])}
183     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
184     */
185    public OSResponse MV(Iterable<String> sources, String target, String... switches)
186        throws IOException
187    { return MV(TO_ARRAY(sources), target, switches); }
188
189    /**
190     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_MV>
191     * 
192     * @param sources A list of arguments that need to be copied, as an array.  <B><I>Can
193     * Include</I></B> wildcards: {@code '*'} and {@code '**'}
194     * 
195     * @param target The target/destination address for the list of files to be copied.
196     * 
197     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'}
198     * with switches.
199     * 
200     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
201     * @throws IOException If there are any problems while invoking the operating-system command
202     * @see OSCommands#printAndRun(String[])
203     */
204    public OSResponse MV(String[] sources, String target, String... switches)
205        throws IOException
206    {
207        String[] command = BUILD_COMMAND
208            (new String[] { "gsutil", "-m", "mv" }, switches, sources, target);
209
210        return printAndRun(command);
211    }
212
213
214    // ********************************************************************************************
215    // ********************************************************************************************
216    // GSUTIL CP 
217    // ********************************************************************************************
218    // ********************************************************************************************
219
220
221    /**
222     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CP>
223     * 
224     * @param source The GCS bucket-storage source-address, or local BASH shell source-address.
225     * <B><I>Can Include</I></B> wildcards: {@code '*'} and {@code '**'}
226     * 
227     * @param target The GCS bucket-storage target-address, or local BASH shell target-address.
228     * 
229     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'}
230     * with switches.
231     * 
232     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
233     * @throws IOException If there are any problems while invoking the operating-system command
234     * @see OSCommands#printAndRun(String[])
235     */
236    public OSResponse CP(String source, String target, String... switches)
237        throws IOException
238    {
239        String[] command = BUILD_COMMAND
240            (new String[] { "gsutil", "-m", "cp" }, switches, source, target);
241
242        return printAndRun(command);
243    }
244
245    /**
246     * Convenience Method.
247     * <BR />Invokes: {@link #CP(String[], String, String[])}
248     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
249     */
250    public OSResponse CP(Iterable<String> sources, String target, String... switches)
251        throws IOException
252    { return CP(TO_ARRAY(sources), target, switches); }
253
254    /**
255     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CP>
256     * 
257     * @param sources A list of arguments that need to be copied, as an array.  <B><I>Can
258     * Include</I></B> wildcards: {@code '*'} and {@code '**'}
259     * 
260     * @param target The target/destination address for the list of files to be copied.
261     * 
262     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'}
263     * with switches.
264     * 
265     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
266     * @throws IOException If there are any problems while invoking the operating-system command
267     * @see OSCommands#printAndRun(String[])
268     */
269    public OSResponse CP(String[] sources, String target, String... switches)
270        throws IOException
271    {
272        String[] command = BUILD_COMMAND
273            (new String[] { "gsutil", "-m", "cp" }, switches, sources, target);
274
275        return printAndRun(command);
276    }
277
278
279    // ********************************************************************************************
280    // ********************************************************************************************
281    // GSUTIL RSYNC
282    // ********************************************************************************************
283    // ********************************************************************************************
284
285
286    /**
287     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_RSYNC>
288     * 
289     * @param sources The source-address.
290     * @param target The target-address.
291     * 
292     * @param switches This may be appended to the command, providing Google's {@code 'gsutil'}
293     * with switches.
294     *
295     * <BR /><BR />'-d' : This will inform GSUTIL to remove files that are not found in the users
296     * directory, but are sitting on the Storage Bucket Server Location - <I>in the
297     * corresponding / same directory</I>
298     *
299     * <BR /><BR />'-r' : This will cause the sync to run recursively.
300     * 
301     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
302     * @throws IOException If there are any problems while invoking the operating-system command
303     * @see OSCommands#printAndRun(String[])
304    */
305    public OSResponse RSYNC(String sources, String target, String... switches)
306        throws IOException
307    {
308        String[] command = BUILD_COMMAND
309            (new String[] { "gsutil", "-m", "rsync" }, switches, sources, target);
310
311        return printAndRun(command);
312    }
313
314
315    // ********************************************************************************************
316    // ********************************************************************************************
317    // GSUTIL Make-Public
318    // ********************************************************************************************
319    // ********************************************************************************************
320
321
322    /**
323     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_MAKE_PUBLIC>
324     * 
325     * @param s1 The GCS bucket file or directory address.  Note {@code '*'} or {@code '**'} may be
326     * used here.
327     * 
328     * @param extraSwitches This may be appended to the command, providing Google's
329     * {@code 'gsutil'} with switches.  The salient arguments to set
330     * the public-visibility of a web-page have already been included.  This parameter is only
331     * important if there are other switches, in addition to the ones already used by the
332     * constructor for this command.
333     * 
334     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
335     * @throws IOException If there are any problems while invoking the operating-system command
336     * @see OSCommands#printAndRun(String[])
337     */
338    public OSResponse MP(String s1, String... extraSwitches) throws IOException
339    {
340        String[] command = BUILD_COMMAND(
341            new String[] { "gsutil", "-m", "acl", "ch", "-u", "AllUsers:R" },
342            extraSwitches, s1, NO_TARGET
343        );
344
345        return printAndRun(command);
346    }
347
348    /**
349     * Convenience Method.
350     * <BR />Invokes: {@link #MP(String[], String[])}
351     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
352     */
353    public OSResponse MP(Iterable<String> iterable, String... extraSwitches)
354        throws IOException
355    { return MP(TO_ARRAY(iterable), extraSwitches); }
356
357    /**
358     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_MAKE_PUBLIC>
359     * 
360     * @param sArr The GCS bucket file or directory addresses.  Note {@code '*'} or
361     * {@code '**'} may be used here.
362     * 
363     * @param extraSwitches This may be appended to the command, providing Google's
364     * {@code 'gsutil'} with switches.  The salient arguments to set
365     * the public-visibility of a web-page have already been included.  This parameter is only
366     * important if there are other switches, in addition to the ones already used by the
367     * constructor for this command.
368     * 
369     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
370     * @throws IOException If there are any problems while invoking the operating-system command
371     * @see OSCommands#printAndRun(String[])
372     */
373    public OSResponse MP(String[] sArr, String... extraSwitches) throws IOException
374    {
375        String[] command = BUILD_COMMAND(
376            new String[] { "gsutil", "-m", "acl", "ch", "-u", "AllUsers:R" },
377            extraSwitches, sArr, NO_TARGET
378        );
379
380        return printAndRun(command);
381    }
382
383
384    // ********************************************************************************************
385    // ********************************************************************************************
386    // GSUTIL Stop Public
387    // ********************************************************************************************
388    // ********************************************************************************************
389
390
391    /**
392     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_STOP_PUBLIC>
393     * 
394     * @param s1 The GCS bucket file or directory address.  Note {@code '*'} or {@code '**'} may be
395     * used here.
396     * 
397     * @param extraSwitches This may be appended to the command, providing Google's
398     * {@code 'gsutil'} with switches.  The salient arguments to stop
399     * the public-visibility of a web-page have already been included.  This parameter is only
400     * important if there are other switches, in addition to the ones already used by the
401     * constructor for this command.
402     * 
403     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
404     * @throws IOException If there are any problems while invoking the operating-system command
405     * @see OSCommands#printAndRun(String[])
406     */
407    public OSResponse SP(String s1, String... extraSwitches) throws IOException
408    {
409        String[] command = BUILD_COMMAND(
410            new String[] { "gsutil", "-m", "acl", "ch", "-d", "AllUsers" },
411            extraSwitches, s1, NO_TARGET
412        );
413
414        return printAndRun(command);
415    }
416
417    /**
418     * Convenience Method.
419     * <BR />Invokes: {@link #SP(String[], String[])}
420     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
421     */
422    public OSResponse SP(Iterable<String> iterable, String... extraSwitches)
423        throws IOException
424    { return SP(TO_ARRAY(iterable), extraSwitches); }
425
426    /**
427     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_STOP_PUBLIC>
428     * 
429     * @param sArr The GCS bucket file or directory address.  Note {@code '*'} or {@code '**'} may
430     * be used here.
431     * 
432     * @param extraSwitches This may be appended to the command, providing Google's
433     * {@code 'gsutil'} with switches.  The salient arguments to stop the public-visibility of a
434     * web-page have already been included.  This parameter is only important if there are other
435     * switches, in addition to the ones already used by the constructor for this command.
436     * 
437     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
438     * @throws IOException If there are any problems while invoking the operating-system command
439     * @see OSCommands#printAndRun(String[])
440     */
441    public OSResponse SP(String[] sArr, String... extraSwitches) throws IOException
442    {
443        String[] command = BUILD_COMMAND(
444            new String[] { "gsutil", "-m", "acl", "ch", "-d", "AllUsers" },
445            extraSwitches, sArr, NO_TARGET
446        );
447
448        return printAndRun(command);
449    }
450
451
452    // ********************************************************************************************
453    // ********************************************************************************************
454    // GSUTIL Set Max Age
455    // ********************************************************************************************
456    // ********************************************************************************************
457
458
459    /**
460     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_SET_MAX_AGE>
461     * 
462     * @param s1 The GCS bucket-storage address.  gs://bucket-name/directoryname/filename
463     * 
464     * <BR /><BR /><DIV CLASS=JDJHint>
465     * "filename" may contain the asterisks {@code '*'} or anything that would normally be passed to
466     * {@code gsutil} on the shell command-line.
467     * </DIV>
468     * 
469     * @param seconds This parameter is added to the end of the max-age= string in the cmdSMA
470     * argument list.  It represents the number of seconds a browser is allowed to cache a page.
471     * 
472     * @param extraSwitches This may be appended to the command, providing Google's
473     * {@code 'gsutil'} with switches.  The salient arguments to set the max-age of a web-page have
474     * already been included.  This parameter is only important if there are other switches, in
475     * addition to the ones already used by the constructor for this command.
476     * 
477     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
478     * @throws IOException If there are any problems while invoking the operating-system command
479     * @see OSCommands#printAndRun(String[])
480     */
481    public OSResponse SMA(String s1, int seconds, String... extraSwitches)
482        throws IOException
483    {
484        String[] command = BUILD_COMMAND(
485            new String[]
486            { 
487                "gsutil", "-m", "setmeta", "-h",
488                ("Cache-Control:public, max-age=" + seconds + "")
489            },
490            extraSwitches, s1, NO_TARGET
491        );
492
493        return printAndRun(command);
494    }
495
496    /**
497     * Convenience Method.
498     * <BR />Invokes: {@link #SMA(String[], int, String[])}.
499     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
500     */
501    public OSResponse SMA(Iterable<String> iterable, int seconds, String... extraSwitches)
502        throws IOException
503    { return SMA(TO_ARRAY(iterable), seconds, extraSwitches); }
504
505    /**
506     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_SET_MAX_AGE>
507     * 
508     * @param seconds This parameter is added to the end of the max-age= string in the cmdSMA
509     * argument list.  It represents the number of seconds a browser is allowed to cache a page.
510     * 
511     * @param extraSwitches This may be appended to the command, providing Google's
512     * {@code 'gsutil'} with switches.  The salient arguments to set the max-age of a web-page have
513     * already been included.  This parameter is only important if there are other switches, in
514     * addition to the ones already used by the constructor for this command.
515     * 
516     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
517     * @throws IOException If there are any problems while invoking the operating-system command
518     * @see OSCommands#printAndRun(String[])
519     */
520    public OSResponse SMA(String[] s1Arr, int seconds, String... extraSwitches)
521        throws IOException
522    {
523        String[] command = BUILD_COMMAND(
524            new String[] 
525            { 
526                "gsutil", "-m", "setmeta", "-h",
527                ("Cache-Control:public, max-age=" + seconds + "")
528            },
529            extraSwitches, s1Arr, NO_TARGET
530        );
531
532        return printAndRun(command);
533    }
534
535
536    // ********************************************************************************************
537    // ********************************************************************************************
538    // GSUTIL Set Content Type
539    // ********************************************************************************************
540    // ********************************************************************************************
541
542
543    /**
544     * Text-File, Plain, UTF-8.
545     * <B>NOTE:</B> May be used for calls to <B>{@code SCT(String s1, String type); }</B>
546     */
547    public static final String SCT_TEXT_UTF8 = "text/plain; charset=utf-8";
548
549    /**
550     * Text-File, HTML, UTF-8.
551     * <B>NOTE:</B> May be used for calls to <B>{@code SCT(String s1, String type); }</B>
552     */
553    public static final String SCT_HTML_UTF8 = "text/html; charset=utf-8";
554
555    /**
556     * Text-file, Java-Script, UTF-8.
557     * <B>NOTE:</B> This is to be used for calls to <B>{@code SCT(String s1, String type); }</B>
558     */
559    public static final String SCT_JAVASCRIPT_UTF8 = "application/javascript; charset=utf-8";
560
561    /**
562     * Text-file, Java-Script.
563     * <B>NOTE:</B> This is to be used for calls to <B>{@code SCT(String s1, String type); }</B>
564     */
565    public static final String SCT_JAVASCRIPT = "application/javascript";
566
567    /**
568     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CONT_TYPE>
569     * 
570     * @param source This is the parameter is supposed to be a file, directory, or expression
571     * sequence.
572     * 
573     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
574     * 
575     * @param type This is any {@code 'String'} that may be used with Google Cloud Server.  Must
576     * pertain to "Content-Type".  There are several pre-defined content-type strings defined in this
577     * class that make reasonable values for this parameter.
578     * 
579     * @param extraSwitches This may be appended to the command, providing Google's
580     * {@code 'gsutil'} with switches.  The salient arguments to set the content-type of a web-page
581     * have already been included.  This parameter is only important if there are other switches,
582     * in addition to the ones already used by the constructor for this command.
583     * 
584     * @see #SCT_TEXT_UTF8
585     * @see #SCT_HTML_UTF8
586     * @see #SCT_JAVASCRIPT
587     * 
588     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
589     * @throws IOException If there are any problems while invoking the operating-system command
590     * @see OSCommands#printAndRun(String[])
591     */
592    public OSResponse CONTENT_TYPE(String source, String type, String... extraSwitches)
593        throws IOException
594    {
595        String[] command = BUILD_COMMAND(
596            new String[] { "gsutil", "-m", "setmeta", "-h", "Content-Type: " + type },
597            extraSwitches, source, NO_TARGET
598        );
599
600        return printAndRun(command);
601    }
602
603    /**
604     * Convenience Method.
605     * <BR />Invokes: {@link #CONTENT_TYPE(String[], String, String[])}
606     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
607     */
608    public OSResponse CONTENT_TYPE
609        (Iterable<String> iterable, String type, String... extraSwitches)
610        throws IOException
611    { return CONTENT_TYPE(TO_ARRAY(iterable), type, extraSwitches); }
612
613    /**
614     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CONT_TYPE>
615     * 
616     * @param s1Arr The GCS bucket-storage address list.
617     * {@code gs://bucket-name/directoryname/filename}
618     * 
619     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
620     * 
621     * @param type This is any {@code 'String'} that may be used with Google Cloud Server.  Must
622     * pertain to "Content-Type".  There are several pre-defined content-type strings defined in
623     * this class that make reasonable values for this parameter.
624     * 
625     * @param extraSwitches This may be appended to the command, providing Google's
626     * {@code 'gsutil'} with switches.  The salient arguments to set the content-type of a web-page
627     * have already been included.  This parameter is only important if there are other switches,
628     * in addition to the ones already used by the constructor for this command.
629     * 
630     * @see #SCT_TEXT_UTF8
631     * @see #SCT_HTML_UTF8
632     * @see #SCT_JAVASCRIPT
633     * 
634     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
635     * @throws IOException If there are any problems while invoking the operating-system command
636     * @see OSCommands#printAndRun(String[])
637     */
638    public OSResponse CONTENT_TYPE(String[] s1Arr, String type, String... extraSwitches)
639        throws IOException
640    {
641        String[] command = BUILD_COMMAND(
642            new String[] { "gsutil", "-m", "setmeta", "-h", "Content-Type: " + type },
643            extraSwitches, s1Arr, NO_TARGET
644        );
645
646        return printAndRun(command);
647    }
648
649
650    // ********************************************************************************************
651    // ********************************************************************************************
652    // GSUTIL CACHE-CONTROL
653    // ********************************************************************************************
654    // ********************************************************************************************
655
656
657    /**
658     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CACHE_CONT>
659     * 
660     * @param s1 This is the parameter is supposed to be a file, directory, or expression sequence
661     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
662     * 
663     * @param cacheControlTags This is any {@code 'String'} that may be used with Google Cloud
664     * Server.  Must pertain to "Cache-Control"
665     * 
666     * @param extraSwitches This may be appended to the command, providing Google's
667     * {@code 'gsutil'} with switches.  The salient arguments to set the cache-control of a web-page
668     * have already been included.  This parameter is only important if there are other switches,
669     * in addition to the ones already used by the constructor for this command.
670     * 
671     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
672     * @throws IOException If there are any problems while invoking the operating-system command
673     * @see OSCommands#printAndRun(String[])
674     */
675    public OSResponse CACHE_CONTROL
676        (String s1, String cacheControlTags, String... extraSwitches)
677        throws IOException
678    {
679        String[] command = BUILD_COMMAND(
680            new String[] { "gsutil", "-m", "setmeta", "-h", "Cache-Control: " + cacheControlTags },
681            extraSwitches, s1, NO_TARGET
682        );
683
684        return printAndRun(command);
685    }
686
687    /**
688     * Convenience Method.
689     * <BR />Invokes: {@link #CACHE_CONTROL(String[], String, String[])}
690     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
691     */
692    public OSResponse CACHE_CONTROL
693        (Iterable<String> iterable, String cacheControlTags, String... extraSwitches)
694        throws IOException
695    { return CACHE_CONTROL(TO_ARRAY(iterable), cacheControlTags, extraSwitches); }
696
697    /**
698     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CACHE_CONT>
699     * 
700     * @param s1Arr This is the parameter is supposed to be a file, directory, or expression
701     * sequence.
702     * 
703     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
704     * 
705     * @param cacheControlTags This is any {@code 'String'} that may be used with Google Cloud
706     * Server.  Must pertain to "Cache-Control"
707     * 
708     * @param extraSwitches This may be appended to the command, providing Google's
709     * {@code 'gsutil'} with switches.  The salient arguments to set the cache-control of a
710     * web-page have already been included.  This parameter is only important if there are other
711     * switches, in addition to the ones already used by the constructor for this command.
712     * 
713     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
714     * @throws IOException If there are any problems while invoking the operating-system command
715     * @see OSCommands#printAndRun(String[])
716     */
717    public OSResponse CACHE_CONTROL
718        (String[] s1Arr, String cacheControlTags, String... extraSwitches)
719        throws IOException
720    {
721        String[] command = BUILD_COMMAND(
722            new String[] { "gsutil", "-m", "setmeta", "-h", "Cache-Control: " + cacheControlTags },
723            extraSwitches, s1Arr, NO_TARGET
724        );
725
726        return printAndRun(command);
727    }
728
729
730    // ********************************************************************************************
731    // ********************************************************************************************
732    // GSUTIL CONTENT-ENCODING
733    // ********************************************************************************************
734    // ********************************************************************************************
735
736
737    /**
738     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CONT_ENCODE>
739     * 
740     * @param s1 This is the parameter is supposed to be a file, directory, or expression sequence
741     * 
742     * <BR /><B>NOTE:</B> The {@code 'source(s)'} may contain the asterisks {@code '*'} or anything
743     * that would normally be passed to gsutil on the shell command-line.
744     * 
745     * @param contentEncodingTags This is any {@code 'String'} that may be used with Google Cloud
746     * Server.  Must pertain to "Content-Encoding"
747     * 
748     * @param extraSwitches This may be appended to the command, providing Google's
749     * {@code 'gsutil'} with switches.  The salient arguments to set the content-encoding of a
750     * web-page have already been included.  This parameter is only important if there are other
751     * switches, in addition to the ones already used by the constructor for this command.
752     * 
753     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
754     * @throws IOException If there are any problems while invoking the operating-system command
755     * @see OSCommands#printAndRun(String[])
756     */
757    public OSResponse CONTENT_ENCODING
758        (String s1, String contentEncodingTags, String... extraSwitches)
759        throws IOException
760    {
761        String[] command = BUILD_COMMAND(
762            new String[]
763                { "gsutil", "-m", "setmeta", "-h", "Content-Encoding: " + contentEncodingTags },
764            extraSwitches, s1, NO_TARGET
765        );
766
767        return printAndRun(command);
768    }
769
770    /**
771     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CONT_ENCODE>
772     * 
773     * @param s1Arr This is the parameter is supposed to be a file, directory, or expression
774     * sequence.
775     * 
776     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
777     * 
778     * @param contentEncodingTags This is any {@code 'String'} that may be used with Google Cloud
779     * Server.  Must pertain to "Content-Encoding"
780     * 
781     * @param extraSwitches This may be appended to the command, providing Google's
782     * {@code 'gsutil'} with switches.  The salient arguments to set the content-encoding of a
783     * web-page have already been included.  This parameter is only important if there are other
784     * switches, in addition to the ones already used by the constructor for this command.
785     * 
786     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
787     * @throws IOException If there are any problems while invoking the operating-system command
788     * @see OSCommands#printAndRun(String[])
789     */
790    public OSResponse CONTENT_ENCODING
791        (String[] s1Arr, String contentEncodingTags, String... extraSwitches)
792        throws IOException
793    {
794        String[] command = BUILD_COMMAND(
795            new String[]
796                { "gsutil", "-m", "setmeta", "-h", "Content-Encoding: " + contentEncodingTags },
797            extraSwitches, s1Arr, NO_TARGET
798        );
799
800        return printAndRun(command);
801    }
802
803    /**
804     * Convenience Method.
805     * <BR />Invokes: {@link #CONTENT_ENCODING(String[], String, String[])}
806     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
807     */
808    public OSResponse CONTENT_ENCODING
809        (Iterable<String> iterable, String contentEncodingTags, String... extraSwitches)
810        throws IOException
811    { return CONTENT_ENCODING(TO_ARRAY(iterable), contentEncodingTags, extraSwitches); }
812
813
814    // ********************************************************************************************
815    // ********************************************************************************************
816    // GSUTIL CONTENT-DISPOSITION
817    // ********************************************************************************************
818    // ********************************************************************************************
819
820
821    /**
822     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CONT_DISP>
823     * 
824     * @param s1 This is the parameter is supposed to be a file, directory, or expression sequence
825     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
826     * 
827     * @param contentDispositionTags This is any {@code 'String'} that may be used with Google
828     * Cloud Server.  Must pertain to "Content-Disposition"
829     * 
830     * @param extraSwitches This may be appended to the command, providing Google's
831     * {@code 'gsutil'} with switches.  The salient arguments to set the content-disposition of a
832     * web-page have already been included.  This parameter is only important if there are other
833     * switches, in addition to the ones already used by the constructor for this command.
834     * 
835     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
836     * @throws IOException If there are any problems while invoking the operating-system command
837     * @see OSCommands#printAndRun(String[])
838     */
839    public OSResponse CONTENT_DISPOSITION
840        (String s1, String contentDispositionTags, String... extraSwitches)
841        throws IOException
842    {
843        String[] command = BUILD_COMMAND(
844            new String[]
845            {
846                "gsutil", "-m", "setmeta", "-h",
847                "Content-Disposition: " + contentDispositionTags
848            },
849            extraSwitches, s1, NO_TARGET
850        );
851
852        return printAndRun(command);
853    }
854
855    /**
856     * Convenience Method.
857     * <BR />Invokes: {@link #CONTENT_DISPOSITION(String[], String, String[])}
858     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
859     */
860    public OSResponse CONTENT_DISPOSITION
861        (Iterable<String> iterable, String contentDispositionTags, String... extraSwitches)
862        throws IOException
863    { return CONTENT_DISPOSITION(TO_ARRAY(iterable), contentDispositionTags, extraSwitches); }
864
865    /**
866     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CONT_DISP>
867     * 
868     * @param s1Arr This is the parameter is supposed to be a file, directory, or expression
869     * sequence.
870     * 
871     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
872     * 
873     * @param contentDispositionTags This is any {@code 'String'} that may be used with Google
874     * Cloud Server.  Must pertain to "Content-Disposition"
875     * 
876     * @param extraSwitches This may be appended to the command, providing Google's
877     * {@code 'gsutil'} with switches.  The salient arguments to set the content-disposition of a
878     * web-page have already been included.  This parameter is only important if there are other
879     * switches, in addition to the ones already used by the constructor for this command.
880     * 
881     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
882     * @throws IOException If there are any problems while invoking the operating-system command
883     * @see OSCommands#printAndRun(String[])
884     */
885    public OSResponse CONTENT_DISPOSITION
886        (String[] s1Arr, String contentDispositionTags, String... extraSwitches)
887        throws IOException
888    {
889        String[] command = BUILD_COMMAND(
890            new String[]
891            {
892                "gsutil", "-m", "setmeta", "-h",
893                "Content-Disposition: " + contentDispositionTags
894            },
895            extraSwitches, s1Arr, NO_TARGET
896        );
897
898        return printAndRun(command);
899    }
900
901
902    // ********************************************************************************************
903    // ********************************************************************************************
904    // GSUTIL OTHER
905    // ********************************************************************************************
906    // ********************************************************************************************
907
908
909    /**
910     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CUSTOM_META>
911     * 
912     * @param s1 This is the parameter is supposed to be a file, directory, or expression sequence
913     * 
914     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
915     * 
916     * @param metaTag This is any {@code 'String'} that may be used with Google Cloud Server's
917     * {@code 'setmeta'} parameter for {@code gsutil}.
918     * 
919     * @param extraSwitches This may be appended to the command, providing Google's
920     * {@code 'gsutil'} with switches.  The salient arguments to set the meta-information of a
921     * web-page have already been included.  This parameter is only important if there are other
922     * switches, in addition to the ones already used by the constructor for this command.
923     * 
924     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
925     * @throws IOException If there are any problems while invoking the operating-system command
926     * @see OSCommands#printAndRun(String[])
927     */
928    public OSResponse CUSTOM_METADATA
929        (String s1, String metaTag, String... extraSwitches)
930        throws IOException
931    {
932        String[] command = BUILD_COMMAND(
933            new String[] { "gsutil", "-m", "setmeta", "-h", metaTag },
934            extraSwitches, s1, NO_TARGET
935        );
936
937        return printAndRun(command);
938    }
939
940    /**
941     * Convenience Method.
942     * <BR />Invokes: {@link #CUSTOM_METADATA(String[], String, String[])}
943     * <BR />Converts: {@code Iterable<String>} to {@code String[] Array}
944     */
945    public OSResponse CUSTOM_METADATA
946        (Iterable<String> iterable, String tags, String... extraSwitches)
947        throws IOException
948    { return CUSTOM_METADATA(TO_ARRAY(iterable), tags, extraSwitches); }
949
950    /**
951     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_CUSTOM_META>
952     * 
953     * @param s1Arr This is the parameter is supposed to be a file, directory, or expression
954     * sequence.
955     * 
956     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_ASTERICKS>
957     * 
958     * @param metaTag This is any {@code 'String'} that may be used with Google Cloud Server's
959     * {@code 'setmeta'} parameter for {@code gsutil}.
960     * 
961     * @param extraSwitches This may be appended to the command, providing Google's
962     * {@code 'gsutil'} with switches.  The salient arguments to set the meta-information of a
963     * web-page have already been included.  This parameter is only important if there are other
964     * switches, in addition to the ones already used by the constructor for this command.
965     * 
966     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
967     * @throws IOException If there are any problems while invoking the operating-system command
968     * @see OSCommands#printAndRun(String[])
969     */
970    public OSResponse CUSTOM_METADATA
971        (String[] s1Arr, String metaTag, String... extraSwitches)
972        throws IOException
973    {
974        String[] command = BUILD_COMMAND(
975            new String[] { "gsutil", "-m", "setmeta", "-h", metaTag },
976            extraSwitches, s1Arr, NO_TARGET
977        );
978
979        return printAndRun(command);
980    }
981
982
983    // ********************************************************************************************
984    // ********************************************************************************************
985    // GSUTIL LS
986    // ********************************************************************************************
987    // ********************************************************************************************
988
989
990    /**
991     * <EMBED CLASS='external-html' DATA-FILE-ID=GSUTIL_LS>
992     * @param s1 The GCS storage file or directory.  Note: {@code '*'} or {@code '**'} may be used.
993     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
994     * @see OSCommands#printAndRun(String[])
995     */
996    public OSResponse LS(String s1, String... switches) throws IOException
997    {
998        String[] command = BUILD_COMMAND(new String[] { "gsutil", "ls" }, switches, s1, NO_TARGET);
999
1000        return printAndRun(command);
1001    }
1002
1003
1004    // ********************************************************************************************
1005    // ********************************************************************************************
1006    // HELPER ROUTINES
1007    // ********************************************************************************************
1008    // ********************************************************************************************
1009
1010
1011    private static String[] TO_ARRAY(Iterable<String> iterable)
1012    {
1013        Stream.Builder<String>  b           = Stream.builder();
1014        Iterator<String>        iterator    = iterable.iterator();
1015
1016        while (iterator.hasNext()) b.add(iterator.next());
1017
1018        return b.build().toArray(String[]::new);
1019    }
1020
1021    private static String[] BUILD_COMMAND
1022        (String[] CMD, String[] SWITCHES, String SOURCE, String TARGET)
1023    {
1024        if (SOURCE == null) throw new NullPointerException
1025            ("You have passed 'null' for a value of your source-file or directory name.");
1026
1027        for (String SWITCH : SWITCHES) if (SWITCH == null) throw new NullPointerException
1028            ("You have passed 'null' as a value for one of your var-args switches.");
1029
1030        if (TARGET == null) throw new NullPointerException
1031            ("You have passed 'null' as a value for your target file or directory name.");
1032
1033        int arrLen = CMD.length + SWITCHES.length + 1 + ((TARGET == NO_TARGET) ? 0 : 1);
1034
1035        String[] ret = new String[arrLen];
1036
1037        for (int i=0; i < CMD.length; i++)
1038            ret[i] = CMD[i];
1039
1040        for (int i=0; i < SWITCHES.length; i++)
1041            ret[CMD.length + i] = SWITCHES[i];
1042
1043        ret[CMD.length + SWITCHES.length] = SOURCE;
1044
1045        if (TARGET != NO_TARGET) ret[ret.length - 1] = TARGET;
1046
1047        return ret;
1048    }
1049
1050    private static String[] BUILD_COMMAND
1051        (String[] CMD, String[] SWITCHES, String[] SOURCES, String TARGET)
1052    {
1053        for (String SOURCE : SOURCES) if (SOURCE == null) throw new NullPointerException
1054            ("You have passed 'null' for a value for one of your source-file or directory names.");
1055
1056        for (String SWITCH : SWITCHES) if (SWITCH == null) throw new NullPointerException
1057            ("You have passed 'null' as a value for one of your var-args switches.");
1058
1059        if (TARGET == null) throw new NullPointerException
1060            ("You have passed 'null' as a value for your target file or directory name.");
1061
1062        int arrLen = CMD.length + SWITCHES.length + SOURCES.length +
1063            ((TARGET == NO_TARGET) ? 0 : 1);
1064
1065        String[] ret = new String[arrLen];
1066
1067        for (int i=0; i < CMD.length; i++)
1068            ret[i] = CMD[i];
1069
1070        for (int i=0; i < SWITCHES.length; i++)
1071            ret[CMD.length + i] = SWITCHES[i];
1072
1073        for (int i=0; i < SOURCES.length; i++) 
1074            ret[CMD.length + SWITCHES.length + i] = SOURCES[i];
1075
1076        if (TARGET != NO_TARGET) ret[ret.length - 1] = TARGET;
1077
1078        return ret;
1079    }
1080}