NbProcessDescriptor


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.openide.execution;
21  
22  import java.io.File  ;
23  import java.io.IOException  ;
24  import java.io.Serializable  ;
25  import java.text.Format  ;
26  import java.util.Arrays  ;
27  import java.util.HashMap  ;
28  import java.util.Iterator  ;
29  import java.util.Map  ;
30  import java.util.logging.Logger  ;
31  import org.openide.util.Utilities;
32  
33  /** Encapsulates start information for a process. It allows the user to
34  * specify the process name to execute and arguments to provide. The progammer
35  * then uses method exec to start the process and can pass additional format that
36  * will be applied to arguments. 
37  * <P>
38  * This allows to define arguments in format -user {USER_NAME} -do {ACTION} and then
39  * use MapFormat with defined values for USER_NAME and ACTION that will be substitued
40  * by into the arguments.
41  *
42  * @author  Ian Formanek, Jaroslav Tulach
43  */
44  public final class NbProcessDescriptor extends Object   implements Serializable   {
45  
46      private static final long serialVersionUID = -4535211234565221486L;
47      
48      /** Logger for logging execs */
49      private static Logger   execLog;
50  
51      /** The name of the executable to run */
52      private String   processName;
53      /** argument format */
54      private String   arguments;
55      /** info about format of the arguments */
56      private String   info;
57  
58      /** Create a new descriptor for the specified process, classpath switch, and classpath.
59      * @param processName     the name of the executable to run
60      * @param arguments string for formating of arguments (may be {@link Utilities#parseParameters quoted})
61      */
62      public NbProcessDescriptor(String   processName, String   arguments) {
63          this (processName, arguments, null);
64      }
65  
66      /** Create a new descriptor for the specified process, classpath switch, and classpath.
67      * @param processName     the name of the executable to run
68      * @param arguments string for formating of arguments (may be {@link Utilities#parseParameters quoted})
69      * @param info info how to format the arguments (human-readable string)
70      */
71      public NbProcessDescriptor(String   processName, String   arguments, String   info) {
72          this.processName = processName;
73          this.arguments = arguments;
74          this.info = info;
75      }
76  
77  
78      /** Get the name of the executable to run.
79      * @return the name
80      */
81      public String   getProcessName () {
82          return processName;
83      }
84  
85      /** Getter the execution arguments of the process.
86      * @return the switch that the executable uses for passing the classpath as its command-line parameter 
87      */
88      public String   getArguments () {
89          return arguments;
90      }
91  
92      /** Getter for the human readable info about the arguments.
93      * @return the info string or null
94      */
95      public String   getInfo () {
96          return info;
97      }
98  
99      /* JST: Commented out, should not be needed.
100     *
101     *  Get the command string and arguments from the supplied process name.
102     * Normally the process name will be the actual name of the process executable,
103     * in which case this method will just return that name by itself.
104     * However, {@link org.openide.util.Utilities#parseParameters} is used
105     * to break apart the string into tokens, so that users may:
106     * <<moved to Utilities.parseParameters Javadoc>>
107     * @return a list of the command name itself and any arguments, unescaped
108     * @see Runtime#exec(String[])
109     *
110     public String[] getProcessArgs() {
111       if (processArguments == null) {
112         processArguments = parseArguments(processName);
113       }
114       return (String[]) processArguments.clone();
115     }
116     */
117 
118     /** Executes the process with arguments formatted by the provided
119     * format. Also the envp properties are passed to the executed process,
120     * and a working directory may be supplied.
121     *
122     * @param format format to be applied to arguments, process and envp supplied by user. It can be <code>null</code> if no formatting should be done.
123     * @param envp list of properties to be applied to the process, or <code>null</code> to leave unspecified
124     * @param cwd the working directory to use, or <code>null</code> if this should not be specified
125     * @return handle to executed process.
126     * @exception IOException if the start of the process fails, or if setting the working directory is not supported
127     */
128     public Process   exec (Format   format, String  [] envp, File   cwd) throws IOException   {
129         return exec (format, envp, false, cwd);
130     }
131     
132     /** Executes the process with arguments, processName and envp formatted by the provided
133     * format. Also the envp properties are passed to the executed process,
134     * and a working directory may be supplied. Optionally the environment variables of the NetBeans JVM may
135     * be appended to (replaced when there is overlap) instead of specifying
136     * all of the environment variables from scratch. This requires the NetBeans core
137     * to translate environment variables to system properties prefixed
138     * by <samp>Env-</samp> in order to work correctly.
139     *
140     * @param format format to be applied to arguments, process and envp supplied by user. It can be <code>null</code> if no formatting should be done.
141     * @param envp list of properties to be applied to the process, or <code>null</code> to leave unspecified
142     * @param appendEnv if true and <code>envp</code> is not <code>null</code>, append or replace JVM's environment
143     * @param cwd the working directory to use, or <code>null</code> if this should not be specified
144     * @return handle to executed process.
145     * @exception IOException if the start of the process fails, or if setting the working directory is not supported
146     * @since 1.15
147     */
148     public Process   exec (Format   format, String  [] envp, boolean appendEnv, File   cwd) throws IOException   {
149         String   stringArgs = format == null ? arguments : format.format (arguments);
150         String  [] args = parseArguments (stringArgs);
151         String  [] call = null;
152         
153         envp = substituteEnv(format, envp);
154        
155         // copy the call string
156         call = new String  [args.length + 1];
157         call[0] = format == null ? processName : format.format(processName);
158         System.arraycopy (args, 0, call, 1, args.length); 
159 
160         logArgs(call);
161         
162         ProcessBuilder   pb = new ProcessBuilder  (call);
163         
164         if (envp != null) {
165             Map  <String  ,String  > e = pb.environment();
166             if (!appendEnv) e.clear();
167             for (int i = 0; i < envp.length; i++) {
168                 String   nameval = envp[i];
169                 int idx = nameval.indexOf ('='); // NOI18N
170                 // [PENDING] add localized annotation...
171                 if (idx == -1) throw new IOException   ("No equal sign in name=value: " + nameval); // NOI18N
172                 e.put (nameval.substring (0, idx), nameval.substring (idx + 1));
173             }
174         }
175 
176         if (cwd != null) pb.directory(cwd);
177         return pb.start();
178     }
179     
180     private static void logArgs(String  [] args) {
181         getExecLog().fine("Running: " + Arrays.asList(args)); // NOI18N
182     }
183 
184     /** Executes the process with arguments and processNme formatted by the provided
185     * format. Also the envp properties are passed to the executed process.
186     *
187     * @param format format to be aplied to arguments, process and envp suplied by user. It can be <code>null</code> if no formatting should be done.
188     * @param envp list of properties to be applied to the process, or <code>null</code> to leave unspecified
189     * @return handle to executed process.
190     * @exception IOException if the start of the process fails
191     */
192     public Process   exec (Format   format, String  [] envp) throws IOException   {
193         return exec (format, envp, null);
194     }
195 
196     /** Executes the process with arguments and processName formatted by the provided
197     * format. 
198     *
199     * @param format format to be aplied to arguments and process. It can be <code>null</code> if no formatting should be done.
200     * @return handle to executed process.
201     * @exception IOException if the start of the process fails
202     */
203     public Process   exec (Format   format) throws IOException   {
204         return exec (format, null);
205     }
206 
207     /** Executes the process with arguments provided in constructor.
208     *
209     * @return handle to executed process.
210     * @exception IOException if the start of the process fails
211     */
212     public Process   exec () throws IOException   {
213         return exec (null, null);
214     }
215 
216     /* hashCode */
217     public int hashCode() {
218         return processName.hashCode() + arguments.hashCode ();
219     }
220 
221     /* equals */
222     public boolean equals(Object   o) {
223         if (! (o instanceof NbProcessDescriptor)) return false;
224         NbProcessDescriptor him = (NbProcessDescriptor) o;
225         return processName.equals(him.processName) && arguments.equals(him.arguments);
226     }
227 
228     /** Parses given string to an array of arguments.
229     * @param sargs is tokenized by spaces unless a space is part of "" token
230     * @return tokenized string
231     */
232     private static String  [] parseArguments(String   sargs) {
233         return Utilities.parseParameters(sargs);
234     }
235     
236     /** Getter for the execLog */
237     private static Logger   getExecLog() {
238         if (execLog == null) {
239             execLog = Logger.getLogger(NbProcessDescriptor.class.getName());
240         }
241         return execLog;
242     }
243     
244     /** Iterates through envp and applies format.format() on values
245      * @param format for formatting, i.e. substitute {filesystems} to /home/phil/dev/classes/pack1:/home/phil/dev/classes/pack2:...
246      * @param envp an String array
247      *
248      * @return substitutet array
249      */
250     private static String  [] substituteEnv(Format   format, String  [] envp) {
251         if (envp == null || envp.length == 0 || format == null) {
252             return envp;
253         }
254         
255         String  [] ret = new String  [envp.length];
256         StringBuffer   adder = new StringBuffer  ();
257         for (int i = 0; i < envp.length; i++) {
258             ret[i] = envp[i];
259             if (ret[i] == null) {
260                 continue;
261             }
262             
263             int idx = ret[i].indexOf('=');
264             if (idx < 0) {
265                 continue;
266             }
267             
268             String   val = ret[i].substring(idx + 1);
269             String   key = ret[i].substring(0, idx);
270             adder.append(key).append('=').append(format.format(val));
271             ret[i] = adder.toString();
272             adder.setLength(0);
273         }
274         
275         return ret;
276     }
277 }
278
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags