8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.io.File;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import java.io.OutputStream;
32 import java.util.Arrays;
33 import java.util.ArrayList;
34 import java.util.List;
35 import java.util.Map;
36
37 /**
38 * This class is used to create operating system processes.
39 *
40 * <p>Each {@code ProcessBuilder} instance manages a collection
41 * of process attributes. The {@link #start()} method creates a new
42 * {@link Process} instance with those attributes. The {@link
43 * #start()} method can be invoked repeatedly from the same instance
44 * to create new subprocesses with identical or related attributes.
45 *
46 * <p>Each process builder manages these process attributes:
47 *
48 * <ul>
49 *
50 * <li>a <i>command</i>, a list of strings which signifies the
51 * external program file to be invoked and its arguments, if any.
442 *
443 * Each {@code Redirect} instance is one of the following:
444 *
445 * <ul>
446 * <li>the special value {@link #PIPE Redirect.PIPE}
447 * <li>the special value {@link #INHERIT Redirect.INHERIT}
448 * <li>a redirection to read from a file, created by an invocation of
449 * {@link Redirect#from Redirect.from(File)}
450 * <li>a redirection to write to a file, created by an invocation of
451 * {@link Redirect#to Redirect.to(File)}
452 * <li>a redirection to append to a file, created by an invocation of
453 * {@link Redirect#appendTo Redirect.appendTo(File)}
454 * </ul>
455 *
456 * <p>Each of the above categories has an associated unique
457 * {@link Type Type}.
458 *
459 * @since 1.7
460 */
461 public static abstract class Redirect {
462 /**
463 * The type of a {@link Redirect}.
464 */
465 public enum Type {
466 /**
467 * The type of {@link Redirect#PIPE Redirect.PIPE}.
468 */
469 PIPE,
470
471 /**
472 * The type of {@link Redirect#INHERIT Redirect.INHERIT}.
473 */
474 INHERIT,
475
476 /**
477 * The type of redirects returned from
478 * {@link Redirect#from Redirect.from(File)}.
479 */
480 READ,
481
482 /**
483 * The type of redirects returned from
484 * {@link Redirect#to Redirect.to(File)}.
485 */
486 WRITE,
487
488 /**
489 * The type of redirects returned from
490 * {@link Redirect#appendTo Redirect.appendTo(File)}.
491 */
498 */
499 public abstract Type type();
500
501 /**
502 * Indicates that subprocess I/O will be connected to the
503 * current Java process over a pipe.
504 *
505 * This is the default handling of subprocess standard I/O.
506 *
507 * <p>It will always be true that
508 * <pre> {@code
509 * Redirect.PIPE.file() == null &&
510 * Redirect.PIPE.type() == Redirect.Type.PIPE
511 * }</pre>
512 */
513 public static final Redirect PIPE = new Redirect() {
514 public Type type() { return Type.PIPE; }
515 public String toString() { return type().toString(); }};
516
517 /**
518 * Indicates that subprocess I/O source or destination will be the
519 * same as those of the current process. This is the normal
520 * behavior of most operating system command interpreters (shells).
521 *
522 * <p>It will always be true that
523 * <pre> {@code
524 * Redirect.INHERIT.file() == null &&
525 * Redirect.INHERIT.type() == Redirect.Type.INHERIT
526 * }</pre>
527 */
528 public static final Redirect INHERIT = new Redirect() {
529 public Type type() { return Type.INHERIT; }
530 public String toString() { return type().toString(); }};
531
532 /**
533 * Returns the {@link File} source or destination associated
534 * with this redirect, or {@code null} if there is no such file.
535 *
536 * @return the file associated with this redirect,
537 * or {@code null} if there is no such file
670 redirects = new Redirect[] {
671 Redirect.PIPE, Redirect.PIPE, Redirect.PIPE
672 };
673 return redirects;
674 }
675
676 /**
677 * Sets this process builder's standard input source.
678 *
679 * Subprocesses subsequently started by this object's {@link #start()}
680 * method obtain their standard input from this source.
681 *
682 * <p>If the source is {@link Redirect#PIPE Redirect.PIPE}
683 * (the initial value), then the standard input of a
684 * subprocess can be written to using the output stream
685 * returned by {@link Process#getOutputStream()}.
686 * If the source is set to any other value, then
687 * {@link Process#getOutputStream()} will return a
688 * <a href="#redirect-input">null output stream</a>.
689 *
690 * @param source the new standard input source
691 * @return this process builder
692 * @throws IllegalArgumentException
693 * if the redirect does not correspond to a valid source
694 * of data, that is, has type
695 * {@link Redirect.Type#WRITE WRITE} or
696 * {@link Redirect.Type#APPEND APPEND}
697 * @since 1.7
698 */
699 public ProcessBuilder redirectInput(Redirect source) {
700 if (source.type() == Redirect.Type.WRITE ||
701 source.type() == Redirect.Type.APPEND)
702 throw new IllegalArgumentException(
703 "Redirect invalid for reading: " + source);
704 redirects()[0] = source;
705 return this;
706 }
707
708 /**
709 * Sets this process builder's standard output destination.
710 *
711 * Subprocesses subsequently started by this object's {@link #start()}
712 * method send their standard output to this destination.
713 *
714 * <p>If the destination is {@link Redirect#PIPE Redirect.PIPE}
715 * (the initial value), then the standard output of a subprocess
716 * can be read using the input stream returned by {@link
717 * Process#getInputStream()}.
718 * If the destination is set to any other value, then
719 * {@link Process#getInputStream()} will return a
720 * <a href="#redirect-output">null input stream</a>.
721 *
722 * @param destination the new standard output destination
723 * @return this process builder
724 * @throws IllegalArgumentException
725 * if the redirect does not correspond to a valid
726 * destination of data, that is, has type
727 * {@link Redirect.Type#READ READ}
728 * @since 1.7
729 */
730 public ProcessBuilder redirectOutput(Redirect destination) {
731 if (destination.type() == Redirect.Type.READ)
732 throw new IllegalArgumentException(
733 "Redirect invalid for writing: " + destination);
734 redirects()[1] = destination;
735 return this;
736 }
737
738 /**
739 * Sets this process builder's standard error destination.
740 *
741 * Subprocesses subsequently started by this object's {@link #start()}
742 * method send their standard error to this destination.
743 *
744 * <p>If the destination is {@link Redirect#PIPE Redirect.PIPE}
745 * (the initial value), then the error output of a subprocess
746 * can be read using the input stream returned by {@link
747 * Process#getErrorStream()}.
748 * If the destination is set to any other value, then
749 * {@link Process#getErrorStream()} will return a
750 * <a href="#redirect-output">null input stream</a>.
751 *
752 * <p>If the {@link #redirectErrorStream() redirectErrorStream}
753 * attribute has been set {@code true}, then the redirection set
754 * by this method has no effect.
755 *
756 * @param destination the new standard error destination
757 * @return this process builder
758 * @throws IllegalArgumentException
759 * if the redirect does not correspond to a valid
760 * destination of data, that is, has type
761 * {@link Redirect.Type#READ READ}
762 * @since 1.7
763 */
764 public ProcessBuilder redirectError(Redirect destination) {
765 if (destination.type() == Redirect.Type.READ)
766 throw new IllegalArgumentException(
767 "Redirect invalid for writing: " + destination);
768 redirects()[2] = destination;
769 return this;
770 }
771
772 /**
773 * Sets this process builder's standard input source to a file.
774 *
775 * <p>This is a convenience method. An invocation of the form
776 * {@code redirectInput(file)}
777 * behaves in exactly the same way as the invocation
778 * {@link #redirectInput(Redirect) redirectInput}
779 * {@code (Redirect.from(file))}.
780 *
781 * @param file the new standard input source
782 * @return this process builder
783 * @since 1.7
784 */
785 public ProcessBuilder redirectInput(File file) {
786 return redirectInput(Redirect.from(file));
787 }
880 * This gives behavior equivalent to most operating system
881 * command interpreters, or the standard C library function
882 * {@code system()}.
883 *
884 * @return this process builder
885 * @since 1.7
886 */
887 public ProcessBuilder inheritIO() {
888 Arrays.fill(redirects(), Redirect.INHERIT);
889 return this;
890 }
891
892 /**
893 * Tells whether this process builder merges standard error and
894 * standard output.
895 *
896 * <p>If this property is {@code true}, then any error output
897 * generated by subprocesses subsequently started by this object's
898 * {@link #start()} method will be merged with the standard
899 * output, so that both can be read using the
900 * {@link Process#getInputStream()} method. This makes it easier
901 * to correlate error messages with the corresponding output.
902 * The initial value is {@code false}.
903 *
904 * @return this process builder's {@code redirectErrorStream} property
905 */
906 public boolean redirectErrorStream() {
907 return redirectErrorStream;
908 }
909
910 /**
911 * Sets this process builder's {@code redirectErrorStream} property.
912 *
913 * <p>If this property is {@code true}, then any error output
914 * generated by subprocesses subsequently started by this object's
915 * {@link #start()} method will be merged with the standard
916 * output, so that both can be read using the
917 * {@link Process#getInputStream()} method. This makes it easier
918 * to correlate error messages with the corresponding output.
919 * The initial value is {@code false}.
920 *
921 * @param redirectErrorStream the new property value
922 * @return this process builder
923 */
924 public ProcessBuilder redirectErrorStream(boolean redirectErrorStream) {
925 this.redirectErrorStream = redirectErrorStream;
926 return this;
927 }
928
929 /**
930 * Starts a new process using the attributes of this process builder.
931 *
932 * <p>The new process will
933 * invoke the command and arguments given by {@link #command()},
934 * in a working directory as given by {@link #directory()},
935 * with a process environment as given by {@link #environment()}.
936 *
937 * <p>This method checks that the command is a valid operating
|
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import sun.nio.ch.SelChImpl;
29
30 import java.io.File;
31 import java.io.IOException;
32 import java.io.InputStream;
33 import java.io.OutputStream;
34 import java.nio.channels.Pipe;
35 import java.util.Arrays;
36 import java.util.ArrayList;
37 import java.util.List;
38 import java.util.Map;
39
40 /**
41 * This class is used to create operating system processes.
42 *
43 * <p>Each {@code ProcessBuilder} instance manages a collection
44 * of process attributes. The {@link #start()} method creates a new
45 * {@link Process} instance with those attributes. The {@link
46 * #start()} method can be invoked repeatedly from the same instance
47 * to create new subprocesses with identical or related attributes.
48 *
49 * <p>Each process builder manages these process attributes:
50 *
51 * <ul>
52 *
53 * <li>a <i>command</i>, a list of strings which signifies the
54 * external program file to be invoked and its arguments, if any.
445 *
446 * Each {@code Redirect} instance is one of the following:
447 *
448 * <ul>
449 * <li>the special value {@link #PIPE Redirect.PIPE}
450 * <li>the special value {@link #INHERIT Redirect.INHERIT}
451 * <li>a redirection to read from a file, created by an invocation of
452 * {@link Redirect#from Redirect.from(File)}
453 * <li>a redirection to write to a file, created by an invocation of
454 * {@link Redirect#to Redirect.to(File)}
455 * <li>a redirection to append to a file, created by an invocation of
456 * {@link Redirect#appendTo Redirect.appendTo(File)}
457 * </ul>
458 *
459 * <p>Each of the above categories has an associated unique
460 * {@link Type Type}.
461 *
462 * @since 1.7
463 */
464 public static abstract class Redirect {
465
466 private static final boolean PIPE_CHANNEL_SUPPORTED;
467
468 static {
469 boolean supported = false;
470 try {
471 Pipe p = Pipe.open();
472 supported = (p.sink() instanceof SelChImpl) &&
473 (p.source() instanceof SelChImpl);
474 try { p.sink().close(); } catch (IOException e) {}
475 try { p.source().close(); } catch (IOException e) {}
476 } catch (IOException e) {
477 // ignore
478 }
479 PIPE_CHANNEL_SUPPORTED = supported;
480 }
481
482 final void checkSupported() throws UnsupportedOperationException {
483 if (this == PIPE_CHANNEL && !PIPE_CHANNEL_SUPPORTED) {
484 throw new UnsupportedOperationException("Unsupported SelectorProvider");
485 }
486 }
487
488 /**
489 * The type of a {@link Redirect}.
490 */
491 public enum Type {
492 /**
493 * The type of {@link Redirect#PIPE Redirect.PIPE}.
494 */
495 PIPE,
496
497 /**
498 * The type of {@link Redirect#PIPE_CHANNEL Redirect.PIPE_CHANNEL}.
499 */
500 PIPE_CHANNEL,
501
502 /**
503 * The type of {@link Redirect#INHERIT Redirect.INHERIT}.
504 */
505 INHERIT,
506
507 /**
508 * The type of redirects returned from
509 * {@link Redirect#from Redirect.from(File)}.
510 */
511 READ,
512
513 /**
514 * The type of redirects returned from
515 * {@link Redirect#to Redirect.to(File)}.
516 */
517 WRITE,
518
519 /**
520 * The type of redirects returned from
521 * {@link Redirect#appendTo Redirect.appendTo(File)}.
522 */
529 */
530 public abstract Type type();
531
532 /**
533 * Indicates that subprocess I/O will be connected to the
534 * current Java process over a pipe.
535 *
536 * This is the default handling of subprocess standard I/O.
537 *
538 * <p>It will always be true that
539 * <pre> {@code
540 * Redirect.PIPE.file() == null &&
541 * Redirect.PIPE.type() == Redirect.Type.PIPE
542 * }</pre>
543 */
544 public static final Redirect PIPE = new Redirect() {
545 public Type type() { return Type.PIPE; }
546 public String toString() { return type().toString(); }};
547
548 /**
549 * Indicates that subprocess I/O will be connected to the
550 * current Java process over a pipe and that the communication
551 * will be performed via {@link java.nio.channels.Pipe.SourceChannel}
552 * or {@link java.nio.channels.Pipe.SinkChannel}.
553 **
554 * <p>It will always be true that
555 * <pre> {@code
556 * Redirect.PIPE_CHANNEL.file() == null &&
557 * Redirect.PIPE_CHANNEL.type() == Redirect.Type.PIPE_CHANNEL
558 * }</pre>
559 *
560 * @since 1.9
561 */
562 public static final Redirect PIPE_CHANNEL = new Redirect() {
563 public Type type() { return Type.PIPE_CHANNEL; }
564 public String toString() { return type().toString(); }};
565
566 /**
567 * Indicates that subprocess I/O source or destination will be the
568 * same as those of the current process. This is the normal
569 * behavior of most operating system command interpreters (shells).
570 *
571 * <p>It will always be true that
572 * <pre> {@code
573 * Redirect.INHERIT.file() == null &&
574 * Redirect.INHERIT.type() == Redirect.Type.INHERIT
575 * }</pre>
576 */
577 public static final Redirect INHERIT = new Redirect() {
578 public Type type() { return Type.INHERIT; }
579 public String toString() { return type().toString(); }};
580
581 /**
582 * Returns the {@link File} source or destination associated
583 * with this redirect, or {@code null} if there is no such file.
584 *
585 * @return the file associated with this redirect,
586 * or {@code null} if there is no such file
719 redirects = new Redirect[] {
720 Redirect.PIPE, Redirect.PIPE, Redirect.PIPE
721 };
722 return redirects;
723 }
724
725 /**
726 * Sets this process builder's standard input source.
727 *
728 * Subprocesses subsequently started by this object's {@link #start()}
729 * method obtain their standard input from this source.
730 *
731 * <p>If the source is {@link Redirect#PIPE Redirect.PIPE}
732 * (the initial value), then the standard input of a
733 * subprocess can be written to using the output stream
734 * returned by {@link Process#getOutputStream()}.
735 * If the source is set to any other value, then
736 * {@link Process#getOutputStream()} will return a
737 * <a href="#redirect-input">null output stream</a>.
738 *
739 * <p>If the source is {@link Redirect#PIPE_CHANNEL Redirect.PIPE_CHANNEL},
740 * then the standard input of a subprocess can be written to
741 * using the output channel returned by
742 * {@link Process#getOutputChannel()} which, unlike the output stream
743 * above, must be obtained and closed by the user.
744 * If the source is set to any other value, then
745 * {@link Process#getOutputChannel()} will return {@code null}.
746 *
747 * @param source the new standard input source
748 * @return this process builder
749 * @throws IllegalArgumentException
750 * if the redirect does not correspond to a valid source
751 * of data, that is, has type
752 * {@link Redirect.Type#WRITE WRITE} or
753 * {@link Redirect.Type#APPEND APPEND}
754 * @throws UnsupportedOperationException if the redirect has type
755 * {@link Redirect.Type#PIPE_CHANNEL PIPE_CHANNEL} and the
756 * platform is configured with unsupported
757 * {@link java.nio.channels.spi.SelectorProvider}
758 * @since 1.7
759 */
760 public ProcessBuilder redirectInput(Redirect source) {
761 if (source.type() == Redirect.Type.WRITE ||
762 source.type() == Redirect.Type.APPEND)
763 throw new IllegalArgumentException(
764 "Redirect invalid for reading: " + source);
765 source.checkSupported();
766 redirects()[0] = source;
767 return this;
768 }
769
770 /**
771 * Sets this process builder's standard output destination.
772 *
773 * Subprocesses subsequently started by this object's {@link #start()}
774 * method send their standard output to this destination.
775 *
776 * <p>If the destination is {@link Redirect#PIPE Redirect.PIPE}
777 * (the initial value), then the standard output of a subprocess
778 * can be read using the input stream returned by {@link
779 * Process#getInputStream()}.
780 * If the destination is set to any other value, then
781 * {@link Process#getInputStream()} will return a
782 * <a href="#redirect-output">null input stream</a>.
783 *
784 * <p>If the destination is {@link Redirect#PIPE_CHANNEL Redirect.PIPE_CHANNEL},
785 * then the standard output of a subprocess can be read using the input
786 * channel returned by {@link Process#getInputChannel()}. which,
787 * unlike the input stream above, must be obtained and closed by the user.
788 * If the destination is set to any other value, then
789 * {@link Process#getInputChannel()} will return {@code null}.
790 *
791 * @param destination the new standard output destination
792 * @return this process builder
793 * @throws IllegalArgumentException
794 * if the redirect does not correspond to a valid
795 * destination of data, that is, has type
796 * {@link Redirect.Type#READ READ}
797 * @throws UnsupportedOperationException if the redirect has type
798 * {@link Redirect.Type#PIPE_CHANNEL PIPE_CHANNEL} and the
799 * platform is configured with unsupported
800 * {@link java.nio.channels.spi.SelectorProvider}
801 * @since 1.7
802 */
803 public ProcessBuilder redirectOutput(Redirect destination) {
804 if (destination.type() == Redirect.Type.READ)
805 throw new IllegalArgumentException(
806 "Redirect invalid for writing: " + destination);
807 destination.checkSupported();
808 redirects()[1] = destination;
809 return this;
810 }
811
812 /**
813 * Sets this process builder's standard error destination.
814 *
815 * Subprocesses subsequently started by this object's {@link #start()}
816 * method send their standard error to this destination.
817 *
818 * <p>If the destination is {@link Redirect#PIPE Redirect.PIPE}
819 * (the initial value), then the error output of a subprocess
820 * can be read using the input stream returned by {@link
821 * Process#getErrorStream()}.
822 * If the destination is set to any other value, then
823 * {@link Process#getErrorStream()} will return a
824 * <a href="#redirect-output">null input stream</a>.
825 *
826 * <p>If the {@link #redirectErrorStream() redirectErrorStream}
827 * attribute has been set {@code true}, then the redirection set
828 * by this method has no effect.
829 *
830 * @param destination the new standard error destination
831 * @return this process builder
832 * @throws IllegalArgumentException
833 * if the redirect does not correspond to a valid
834 * destination of data, that is, has type
835 * {@link Redirect.Type#READ READ}
836 * @throws UnsupportedOperationException if the redirect has type
837 * {@link Redirect.Type#PIPE_CHANNEL PIPE_CHANNEL} and the
838 * platform is configured with unsupported
839 * {@link java.nio.channels.spi.SelectorProvider}
840 * @since 1.7
841 */
842 public ProcessBuilder redirectError(Redirect destination) {
843 if (destination.type() == Redirect.Type.READ)
844 throw new IllegalArgumentException(
845 "Redirect invalid for writing: " + destination);
846 destination.checkSupported();
847 redirects()[2] = destination;
848 return this;
849 }
850
851 /**
852 * Sets this process builder's standard input source to a file.
853 *
854 * <p>This is a convenience method. An invocation of the form
855 * {@code redirectInput(file)}
856 * behaves in exactly the same way as the invocation
857 * {@link #redirectInput(Redirect) redirectInput}
858 * {@code (Redirect.from(file))}.
859 *
860 * @param file the new standard input source
861 * @return this process builder
862 * @since 1.7
863 */
864 public ProcessBuilder redirectInput(File file) {
865 return redirectInput(Redirect.from(file));
866 }
959 * This gives behavior equivalent to most operating system
960 * command interpreters, or the standard C library function
961 * {@code system()}.
962 *
963 * @return this process builder
964 * @since 1.7
965 */
966 public ProcessBuilder inheritIO() {
967 Arrays.fill(redirects(), Redirect.INHERIT);
968 return this;
969 }
970
971 /**
972 * Tells whether this process builder merges standard error and
973 * standard output.
974 *
975 * <p>If this property is {@code true}, then any error output
976 * generated by subprocesses subsequently started by this object's
977 * {@link #start()} method will be merged with the standard
978 * output, so that both can be read using the
979 * {@link Process#getInputStream()} or {@link Process#getInputChannel()}
980 * methods. This makes it easier
981 * to correlate error messages with the corresponding output.
982 * The initial value is {@code false}.
983 *
984 * @return this process builder's {@code redirectErrorStream} property
985 */
986 public boolean redirectErrorStream() {
987 return redirectErrorStream;
988 }
989
990 /**
991 * Sets this process builder's {@code redirectErrorStream} property.
992 *
993 * <p>If this property is {@code true}, then any error output
994 * generated by subprocesses subsequently started by this object's
995 * {@link #start()} method will be merged with the standard
996 * output, so that both can be read using the
997 * {@link Process#getInputStream()} or {@link Process#getInputChannel()}
998 * methods. This makes it easier
999 * to correlate error messages with the corresponding output.
1000 * The initial value is {@code false}.
1001 *
1002 * @param redirectErrorStream the new property value
1003 * @return this process builder
1004 */
1005 public ProcessBuilder redirectErrorStream(boolean redirectErrorStream) {
1006 this.redirectErrorStream = redirectErrorStream;
1007 return this;
1008 }
1009
1010 /**
1011 * Starts a new process using the attributes of this process builder.
1012 *
1013 * <p>The new process will
1014 * invoke the command and arguments given by {@link #command()},
1015 * in a working directory as given by {@link #directory()},
1016 * with a process environment as given by {@link #environment()}.
1017 *
1018 * <p>This method checks that the command is a valid operating
|