001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.launching;
011:
012: import java.util.Map;
013:
014: import org.eclipse.jdt.internal.launching.LaunchingMessages;
015:
016: /**
017: * Holder for various arguments passed to a VM runner.
018: * Mandatory parameters are passed in the constructor; optional arguments, via setters.
019: * <p>
020: * Clients may instantiate this class; it is not intended to be subclassed.
021: * </p>
022: */
023: public class VMRunnerConfiguration {
024: private String fClassToLaunch;
025: private String[] fVMArgs;
026: private String[] fProgramArgs;
027: private String[] fEnvironment;
028: private String[] fClassPath;
029: private String[] fBootClassPath;
030: private String fWorkingDirectory;
031: private Map fVMSpecificAttributesMap;
032: private boolean fResume = true;
033:
034: private static final String[] fgEmpty = new String[0];
035:
036: /**
037: * Creates a new configuration for launching a VM to run the given main class
038: * using the given class path.
039: *
040: * @param classToLaunch The fully qualified name of the class to launch. May not be null.
041: * @param classPath The classpath. May not be null.
042: */
043: public VMRunnerConfiguration(String classToLaunch,
044: String[] classPath) {
045: if (classToLaunch == null) {
046: throw new IllegalArgumentException(
047: LaunchingMessages.vmRunnerConfig_assert_classNotNull);
048: }
049: if (classPath == null) {
050: throw new IllegalArgumentException(
051: LaunchingMessages.vmRunnerConfig_assert_classPathNotNull);
052: }
053: fClassToLaunch = classToLaunch;
054: fClassPath = classPath;
055: }
056:
057: /**
058: * Sets the <code>Map</code> that contains String name/value pairs that represent
059: * VM-specific attributes.
060: *
061: * @param map the <code>Map</code> of VM-specific attributes.
062: * @since 2.0
063: */
064: public void setVMSpecificAttributesMap(Map map) {
065: fVMSpecificAttributesMap = map;
066: }
067:
068: /**
069: * Sets the custom VM arguments. These arguments will be appended to the list of
070: * VM arguments that a VM runner uses when launching a VM. Typically, these VM arguments
071: * are set by the user.
072: * These arguments will not be interpreted by a VM runner, the client is responsible for
073: * passing arguments compatible with a particular VM runner.
074: *
075: * @param args the list of VM arguments
076: */
077: public void setVMArguments(String[] args) {
078: if (args == null) {
079: throw new IllegalArgumentException(
080: LaunchingMessages.vmRunnerConfig_assert_vmArgsNotNull);
081: }
082: fVMArgs = args;
083: }
084:
085: /**
086: * Sets the custom program arguments. These arguments will be appended to the list of
087: * program arguments that a VM runner uses when launching a VM (in general: none).
088: * Typically, these VM arguments are set by the user.
089: * These arguments will not be interpreted by a VM runner, the client is responsible for
090: * passing arguments compatible with a particular VM runner.
091: *
092: * @param args the list of arguments
093: */
094: public void setProgramArguments(String[] args) {
095: if (args == null) {
096: throw new IllegalArgumentException(
097: LaunchingMessages.vmRunnerConfig_assert_programArgsNotNull);
098: }
099: fProgramArgs = args;
100: }
101:
102: /**
103: * Sets the environment for the Java program. The Java VM will be
104: * launched in the given environment.
105: *
106: * @param environment the environment for the Java program specified as an array
107: * of strings, each element specifying an environment variable setting in the
108: * format <i>name</i>=<i>value</i>
109: * @since 3.0
110: */
111: public void setEnvironment(String[] environment) {
112: fEnvironment = environment;
113: }
114:
115: /**
116: * Sets the boot classpath. Note that the boot classpath will be passed to the
117: * VM "as is". This means it has to be complete. Interpretation of the boot class path
118: * is up to the VM runner this object is passed to.
119: * <p>
120: * In release 3.0, support has been added for appending and prepending the
121: * boot classpath. Generally an <code>IVMRunner</code> should use the prepend,
122: * main, and append boot classpaths provided. However, in the case that an
123: * <code>IVMRunner</code> does not support these options, a complete bootpath
124: * should also be specified.
125: * </p>
126: * @param bootClassPath The boot classpath. An empty array indicates an empty
127: * bootpath and <code>null</code> indicates a default bootpath.
128: */
129: public void setBootClassPath(String[] bootClassPath) {
130: fBootClassPath = bootClassPath;
131: }
132:
133: /**
134: * Returns the <code>Map</code> that contains String name/value pairs that represent
135: * VM-specific attributes.
136: *
137: * @return The <code>Map</code> of VM-specific attributes or <code>null</code>.
138: * @since 2.0
139: */
140: public Map getVMSpecificAttributesMap() {
141: return fVMSpecificAttributesMap;
142: }
143:
144: /**
145: * Returns the name of the class to launch.
146: *
147: * @return The fully qualified name of the class to launch. Will not be <code>null</code>.
148: */
149: public String getClassToLaunch() {
150: return fClassToLaunch;
151: }
152:
153: /**
154: * Returns the classpath.
155: *
156: * @return the classpath
157: */
158: public String[] getClassPath() {
159: return fClassPath;
160: }
161:
162: /**
163: * Returns the boot classpath. An empty array indicates an empty
164: * bootpath and <code>null</code> indicates a default bootpath.
165: * <p>
166: * In 3.0, support has been added for prepending and appending to the
167: * boot classpath. The new attributes are stored in the VM specific
168: * attributes map using the following keys defined in
169: * <code>IJavaLaunchConfigurationConstants</code>:
170: * <ul>
171: * <li>ATTR_BOOTPATH_PREPEND</li>
172: * <li>ATTR_BOOTPATH_APPEND</li>
173: * <li>ATTR_BOOTPATH</li>
174: * </ul>
175: * </p>
176: * @return The boot classpath. An empty array indicates an empty
177: * bootpath and <code>null</code> indicates a default bootpath.
178: * @see #setBootClassPath(String[])
179: * @see IJavaLaunchConfigurationConstants
180: */
181: public String[] getBootClassPath() {
182: return fBootClassPath;
183: }
184:
185: /**
186: * Returns the arguments to the VM itself.
187: *
188: * @return The VM arguments. Default is an empty array. Will not be <code>null</code>.
189: * @see #setVMArguments(String[])
190: */
191: public String[] getVMArguments() {
192: if (fVMArgs == null) {
193: return fgEmpty;
194: }
195: return fVMArgs;
196: }
197:
198: /**
199: * Returns the arguments to the Java program.
200: *
201: * @return The Java program arguments. Default is an empty array. Will not be <code>null</code>.
202: * @see #setProgramArguments(String[])
203: */
204: public String[] getProgramArguments() {
205: if (fProgramArgs == null) {
206: return fgEmpty;
207: }
208: return fProgramArgs;
209: }
210:
211: /**
212: * Returns the environment for the Java program or <code>null</code>
213: *
214: * @return The Java program environment. Default is <code>null</code>
215: * @since 3.0
216: */
217: public String[] getEnvironment() {
218: return fEnvironment;
219: }
220:
221: /**
222: * Sets the working directory for a launched VM.
223: *
224: * @param path the absolute path to the working directory
225: * to be used by a launched VM, or <code>null</code> if
226: * the default working directory is to be inherited from the
227: * current process
228: * @since 2.0
229: */
230: public void setWorkingDirectory(String path) {
231: fWorkingDirectory = path;
232: }
233:
234: /**
235: * Returns the working directory of a launched VM.
236: *
237: * @return the absolute path to the working directory
238: * of a launched VM, or <code>null</code> if the working
239: * directory is inherited from the current process
240: * @since 2.0
241: */
242: public String getWorkingDirectory() {
243: return fWorkingDirectory;
244: }
245:
246: /**
247: * Sets whether the VM is resumed on startup when launched in
248: * debug mode. Has no effect when not in debug mode.
249: *
250: * @param resume whether to resume the VM on startup
251: * @since 3.0
252: */
253: public void setResumeOnStartup(boolean resume) {
254: fResume = resume;
255: }
256:
257: /**
258: * Returns whether the VM is resumed on startup when launched
259: * in debug mode. Has no effect when no in debug mode. Default
260: * value is <code>true</code> for backwards compatibility.
261: *
262: * @return whether to resume the VM on startup
263: * @since 3.0
264: */
265: public boolean isResumeOnStartup() {
266: return fResume;
267: }
268: }
|