1. /*
  2. * @(#)Runtime.java 1.50 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.lang;
  8. import java.io.*;
  9. import java.util.StringTokenizer;
  10. /**
  11. * Every Java application has a single instance of class
  12. * <code>Runtime</code> that allows the application to interface with
  13. * the environment in which the application is running. The current
  14. * runtime can be obtained from the <code>getRuntime</code> method.
  15. * <p>
  16. * An application cannot create its own instance of this class.
  17. *
  18. * @author unascribed
  19. * @version 1.50, 11/29/01
  20. * @see java.lang.Runtime#getRuntime()
  21. * @since JDK1.0
  22. */
  23. public class Runtime {
  24. private static Runtime currentRuntime = new Runtime();
  25. /**
  26. * Returns the runtime object associated with the current Java application.
  27. * Most of the methods of class <code>Runtime</code> are instance
  28. * methods and must be invoked with respect to the current runtime object.
  29. *
  30. * @return the <code>Runtime</code> object associated with the current
  31. * Java application.
  32. */
  33. public static Runtime getRuntime() {
  34. return currentRuntime;
  35. }
  36. /** Don't let anyone else instantiate this class */
  37. private Runtime() {}
  38. /* Helper for exit
  39. */
  40. private native void exitInternal(int status);
  41. /**
  42. * Terminates the currently running Java Virtual Machine. This
  43. * method never returns normally.
  44. * <p>
  45. * First, if there is a security manager, its <code>checkExit</code>
  46. * method is called with the status as its argument. This may result
  47. * in a security exception.
  48. * <p>
  49. * The argument serves as a status code; by convention, a nonzero
  50. * status code indicates abnormal termination.
  51. * <p>
  52. * The method {@link System#exit(int)} is the conventional and
  53. * convenient means of invoking this method.
  54. *
  55. * @param status exit status. By convention, a nonzero status
  56. * code indicates abnormal termination.
  57. * @throws SecurityException
  58. * if a security manager exists and its <code>checkExit</code>
  59. * method doesn't allow exit with the specified status.
  60. * @see java.lang.SecurityException
  61. * @see java.lang.SecurityManager#checkExit(int)
  62. */
  63. public void exit(int status) {
  64. SecurityManager security = System.getSecurityManager();
  65. if (security != null) {
  66. security.checkExit(status);
  67. }
  68. exitInternal(status);
  69. }
  70. /* Wormhole for calling java.lang.ref.Finalizer.setRunFinalizersOnExit */
  71. private static native void runFinalizersOnExit0(boolean value);
  72. /**
  73. * Enable or disable finalization on exit; doing so specifies that the
  74. * finalizers of all objects that have finalizers that have not yet been
  75. * automatically invoked are to be run before the Java runtime exits.
  76. * By default, finalization on exit is disabled.
  77. *
  78. * <p>If there is a security manager,
  79. * its <code>checkExit</code> method is first called
  80. * with 0 as its argument to ensure the exit is allowed.
  81. * This could result in a SecurityException.
  82. *
  83. * @deprecated This method is inherently unsafe. It may result in
  84. * finalizers being called on live objects while other threads are
  85. * concurrently manipulating those objects, resulting in erratic
  86. * behavior or deadlock.
  87. *
  88. * @throws SecurityException
  89. * if a security manager exists and its <code>checkExit</code>
  90. * method doesn't allow the exit.
  91. *
  92. * @see java.lang.Runtime#exit(int)
  93. * @see java.lang.Runtime#gc()
  94. * @see java.lang.SecurityManager#checkExit(int)
  95. * @since JDK1.1
  96. */
  97. public static void runFinalizersOnExit(boolean value) {
  98. SecurityManager security = System.getSecurityManager();
  99. if (security != null) {
  100. try {
  101. security.checkExit(0);
  102. } catch (SecurityException e) {
  103. throw new SecurityException("runFinalizersOnExit");
  104. }
  105. }
  106. runFinalizersOnExit0(value);
  107. }
  108. /* Helper for exec
  109. */
  110. private native Process execInternal(String cmdarray[], String envp[])
  111. throws IOException;
  112. /**
  113. * Executes the specified string command in a separate process.
  114. * <p>
  115. * The <code>command</code> argument is parsed into tokens and then
  116. * executed as a command in a separate process. The token parsing is
  117. * done by a {@link java.util.StringTokenizer} created by the call:
  118. * <blockquote><pre>
  119. * new StringTokenizer(command)
  120. * </pre></blockquote>
  121. * with no further modifications of the character categories.
  122. * This method has exactly the same effect as
  123. * <code>exec(command, null)</code>.
  124. *
  125. * @param command a specified system command.
  126. * @return a <code>Process</code> object for managing the subprocess.
  127. * @exception SecurityException if a security manager exists and its
  128. * <code>checkExec</code> method doesn't allow creation of a subprocess.
  129. * @see java.lang.Runtime#exec(java.lang.String, java.lang.String[])
  130. * @see java.lang.SecurityManager#checkExec(java.lang.String)
  131. */
  132. public Process exec(String command) throws IOException {
  133. return exec(command, null);
  134. }
  135. /**
  136. * Executes the specified string command in a separate process with the
  137. * specified environment.
  138. * <p>
  139. * This method breaks the <code>command</code> string into tokens and
  140. * creates a new array <code>cmdarray</code> containing the tokens in the
  141. * order that they were produced by the string tokenizer; it
  142. * then performs the call <code>exec(cmdarray, envp)</code>. The token
  143. * parsing is done by a {@link java.util.StringTokenizer} created by
  144. * the call:
  145. * <blockquote><pre>
  146. * new StringTokenizer(command)
  147. * </pre></blockquote>
  148. * with no further modification of the character categories.
  149. *
  150. * @param command a specified system command.
  151. * @param envp array of strings, each element of which
  152. * has environment variable settings in format
  153. * <i>name</i>=<i>value</i>.
  154. * @return a <code>Process</code> object for managing the subprocess.
  155. * @exception SecurityException if a security manager exists and its
  156. * <code>checkExec</code> method doesn't allow creation of a subprocess.
  157. * @see java.lang.Runtime#exec(java.lang.String[])
  158. * @see java.lang.Runtime#exec(java.lang.String[], java.lang.String[])
  159. * @see java.lang.SecurityManager#checkExec(java.lang.String)
  160. */
  161. public Process exec(String command, String envp[]) throws IOException {
  162. int count = 0;
  163. String cmdarray[];
  164. StringTokenizer st;
  165. st = new StringTokenizer(command);
  166. count = st.countTokens();
  167. cmdarray = new String[count];
  168. st = new StringTokenizer(command);
  169. count = 0;
  170. while (st.hasMoreTokens()) {
  171. cmdarray[count++] = st.nextToken();
  172. }
  173. return exec(cmdarray, envp);
  174. }
  175. /**
  176. * Executes the specified command and arguments in a separate process.
  177. * <p>
  178. * The command specified by the tokens in <code>cmdarray</code> is
  179. * executed as a command in a separate process. This has exactly the
  180. * same effect as <code>exec(cmdarray, null)</code>.
  181. * <p>
  182. * If there is a security manager, its <code>checkExec</code>
  183. * method is called with the first component of the array
  184. * <code>cmdarray</code> as its argument. This may result in a security
  185. * exception.
  186. *
  187. * @param cmdarray array containing the command to call and
  188. * its arguments.
  189. * @return a <code>Process</code> object for managing the subprocess.
  190. * @exception SecurityException if a security manager exists and its
  191. * <code>checkExec</code> method doesn't allow creation of a subprocess.
  192. * @see java.lang.Runtime#exec(java.lang.String[], java.lang.String[])
  193. * @see java.lang.SecurityManager#checkExec(java.lang.String)
  194. */
  195. public Process exec(String cmdarray[]) throws IOException {
  196. return exec(cmdarray, null);
  197. }
  198. /**
  199. * Executes the specified command and arguments in a separate process
  200. * with the specified environment.
  201. * <p>
  202. * If there is a security manager, its <code>checkExec</code>
  203. * method is called with the first component of the array
  204. * <code>cmdarray</code> as its argument. This may result in a security
  205. * exception.
  206. * <p>
  207. * Given an array of strings <code>cmdarray</code>, representing the
  208. * tokens of a command line, and an array of strings <code>envp</code>,
  209. * representing "environment" variable settings, this method creates
  210. * a new process in which to execute the specified command.
  211. *
  212. * @param cmdarray array containing the command to call and
  213. * its arguments.
  214. * @param envp array of strings, each element of which
  215. * has environment variable settings in format
  216. * <i>name</i>=<i>value</i>.
  217. * @return a <code>Process</code> object for managing the subprocess.
  218. * @exception SecurityException if a security manager exists and its
  219. * <code>checkExec</code> method doesn't allow creation of a subprocess.
  220. * @exception NullPointerException if <code>cmdarray</code> is
  221. * <code>null</code>.
  222. * @exception IndexOutOfBoundsException if <code>cmdarray</code> is an
  223. * empty array (has length <code>0</code>).
  224. * @see java.lang.Process
  225. * @see java.lang.SecurityException
  226. * @see java.lang.SecurityManager#checkExec(java.lang.String)
  227. */
  228. public Process exec(String cmdarray[], String envp[]) throws IOException {
  229. cmdarray = (String[])cmdarray.clone();
  230. envp = (envp != null ? (String[])envp.clone() : null);
  231. if (cmdarray.length == 0) {
  232. throw new IndexOutOfBoundsException();
  233. }
  234. for (int i = 0; i < cmdarray.length; i++) {
  235. if (cmdarray[i] == null) {
  236. throw new NullPointerException();
  237. }
  238. }
  239. if (envp != null) {
  240. for (int i = 0; i < envp.length; i++) {
  241. if (envp[i] == null) {
  242. throw new NullPointerException();
  243. }
  244. }
  245. }
  246. SecurityManager security = System.getSecurityManager();
  247. if (security != null) {
  248. security.checkExec(cmdarray[0]);
  249. }
  250. return execInternal(cmdarray, envp);
  251. }
  252. /**
  253. * Returns the amount of free memory in the system. Calling the
  254. * <code>gc</code> method may result in increasing the value returned
  255. * by <code>freeMemory.</code>
  256. *
  257. * @return an approximation to the total amount of memory currently
  258. * available for future allocated objects, measured in bytes.
  259. */
  260. public native long freeMemory();
  261. /**
  262. * Returns the total amount of memory in the Java Virtual Machine.
  263. * The value returned by this method may vary over time, depending on
  264. * the host environment.
  265. * <p>
  266. * Note that the amount of memory required to hold an object of any
  267. * given type may be implementation-dependent.
  268. *
  269. * @return the total amount of memory currently available for current
  270. * and future objects, measured in bytes.
  271. */
  272. public native long totalMemory();
  273. /**
  274. * Runs the garbage collector.
  275. * Calling this method suggests that the Java Virtual Machine expend
  276. * effort toward recycling unused objects in order to make the memory
  277. * they currently occupy available for quick reuse. When control
  278. * returns from the method call, the Java Virtual Machine has made
  279. * its best effort to recycle all discarded objects.
  280. * <p>
  281. * The name <code>gc</code> stands for "garbage
  282. * collector". The Java Virtual Machine performs this recycling
  283. * process automatically as needed, in a separate thread, even if the
  284. * <code>gc</code> method is not invoked explicitly.
  285. * <p>
  286. * The method {@link System#gc()} is hte conventional and convenient
  287. * means of invoking this method.
  288. */
  289. public native void gc();
  290. /* Wormhole for calling java.lang.ref.Finalizer.runFinalization */
  291. private static native void runFinalization0();
  292. /**
  293. * Runs the finalization methods of any objects pending finalization.
  294. * Calling this method suggests that the Java Virtual Machine expend
  295. * effort toward running the <code>finalize</code> methods of objects
  296. * that have been found to be discarded but whose <code>finalize</code>
  297. * methods have not yet been run. When control returns from the
  298. * method call, the Java Virtual Machine has made a best effort to
  299. * complete all outstanding finalizations.
  300. * <p>
  301. * The Java Virtual Machine performs the finalization process
  302. * automatically as needed, in a separate thread, if the
  303. * <code>runFinalization</code> method is not invoked explicitly.
  304. * <p>
  305. * The method {@link System#runFinalization()} is the conventional
  306. * and convenient means of invoking this method.
  307. *
  308. * @see java.lang.Object#finalize()
  309. */
  310. public void runFinalization() {
  311. runFinalization0();
  312. }
  313. /**
  314. * Enables/Disables tracing of instructions.
  315. * If the <code>boolean</code> argument is <code>true</code>, this
  316. * method suggests that the Java Virtual Machine emit debugging
  317. * information for each instruction in the Java Virtual Machine as it
  318. * is executed. The format of this information, and the file or other
  319. * output stream to which it is emitted, depends on the host environment.
  320. * The virtual machine may ignore this request if it does not support
  321. * this feature. The destination of the trace output is system
  322. * dependent.
  323. * <p>
  324. * If the <code>boolean</code> argument is <code>false</code>, this
  325. * method causes the Java Virtual Machine to stop performing the
  326. * detailed instruction trace it is performing.
  327. *
  328. * @param on <code>true</code> to enable instruction tracing;
  329. * <code>false</code> to disable this feature.
  330. */
  331. public native void traceInstructions(boolean on);
  332. /**
  333. * Enables/Disables tracing of method calls.
  334. * If the <code>boolean</code> argument is <code>true</code>, this
  335. * method suggests that the Java Virtual Machine emit debugging
  336. * information for each method in the Java Virtual Machine as it is
  337. * called. The format of this information, and the file or other output
  338. * stream to which it is emitted, depends on the host environment. The
  339. * virtual machine may ignore this request if it does not support
  340. * this feature.
  341. * <p>
  342. * Calling this method with argument false suggests that the Java
  343. * Virtual Machine cease emitting per-call debugging information.
  344. *
  345. * @param on <code>true</code> to enable instruction tracing;
  346. * <code>false</code> to disable this feature.
  347. */
  348. public native void traceMethodCalls(boolean on);
  349. /**
  350. * Loads the specified filename as a dynamic library. The filename
  351. * argument must be a complete pathname.
  352. * From <code>java_g</code> it will automagically insert "_g" before the
  353. * ".so" (for example
  354. * <code>Runtime.getRuntime().load("/home/avh/lib/libX11.so");</code>).
  355. * <p>
  356. * First, if there is a security manager, its <code>checkLink</code>
  357. * method is called with the <code>filename</code> as its argument.
  358. * This may result in a security exception.
  359. * <p>
  360. * This is similar to the method {@link #loadLibrary(String)}, but it
  361. * accepts a general file name as an argument rathan than just a library
  362. * name, allowing any file of native code to be loaded.
  363. * <p>
  364. * The method {@link System#load(String)} is the conventional and
  365. * convenient means of invoking this method.
  366. *
  367. * @param filename the file to load.
  368. * @exception SecurityException if a security manager exists and its
  369. * <code>checkLink</code> method doesn't allow
  370. * loading of the specified dynamic library
  371. * @exception UnsatisfiedLinkError if the file does not exist.
  372. * @see java.lang.Runtime#getRuntime()
  373. * @see java.lang.SecurityException
  374. * @see java.lang.SecurityManager#checkLink(java.lang.String)
  375. */
  376. public void load(String filename) {
  377. load0(System.getCallerClass(), filename);
  378. }
  379. synchronized void load0(Class fromClass, String filename) {
  380. SecurityManager security = System.getSecurityManager();
  381. if (security != null) {
  382. security.checkLink(filename);
  383. }
  384. if (!(new File(filename).isAbsolute())) {
  385. throw new UnsatisfiedLinkError(
  386. "Expecting an absolute path of the library: " + filename);
  387. }
  388. ClassLoader.loadLibrary(fromClass, filename, true);
  389. }
  390. /**
  391. * Loads the dynamic library with the specified library name.
  392. * A file containing native code is loaded from the local file system
  393. * from a place where library files are conventionally obtained. The
  394. * details of this process are implementation-dependent. The
  395. * mapping from a library name to a specific filename is done in a
  396. * system-specific manner.
  397. * <p>
  398. * First, if there is a security manager, its <code>checkLink</code>
  399. * method is called with the <code>libname</code> as its argument.
  400. * This may result in a security exception.
  401. * <p>
  402. * The method {@link System#loadLibrary(String)} is the conventional
  403. * and convenient means of invoking this method. If native
  404. * methods are to be used in the implementation of a class, a standard
  405. * strategy is to put the native code in a library file (call it
  406. * <code>LibFile</code>) and then to put a static initializer:
  407. * <blockquote><pre>
  408. * static { System.loadLibrary("LibFile"); }
  409. * </pre></blockquote>
  410. * within the class declaration. When the class is loaded and
  411. * initialized, the necessary native code implementation for the native
  412. * methods will then be loaded as well.
  413. * <p>
  414. * If this method is called more than once with the same library
  415. * name, the second and subsequent calls are ignored.
  416. *
  417. * @param libname the name of the library.
  418. * @exception SecurityException if a security manager exists and its
  419. * <code>checkLink</code> method doesn't allow
  420. * loading of the specified dynamic library
  421. * @exception UnsatisfiedLinkError if the library does not exist.
  422. * @see java.lang.SecurityException
  423. * @see java.lang.SecurityManager#checkLink(java.lang.String)
  424. */
  425. public void loadLibrary(String libname) {
  426. loadLibrary0(System.getCallerClass(), libname);
  427. }
  428. synchronized void loadLibrary0(Class fromClass, String libname) {
  429. SecurityManager security = System.getSecurityManager();
  430. if (security != null) {
  431. security.checkLink(libname);
  432. }
  433. if (libname.indexOf((int)File.separatorChar) != -1) {
  434. throw new UnsatisfiedLinkError(
  435. "Directory separator should not appear in library name: " + libname);
  436. }
  437. ClassLoader.loadLibrary(fromClass, libname, false);
  438. }
  439. /**
  440. * Creates a localized version of an input stream. This method takes
  441. * an <code>InputStream</code> and returns an <code>InputStream</code>
  442. * equivalent to the argument in all respects except that it is
  443. * localized: as characters in the local character set are read from
  444. * the stream, they are automatically converted from the local
  445. * character set to Unicode.
  446. * <p>
  447. * If the argument is already a localized stream, it may be returned
  448. * as the result.
  449. *
  450. * @deprecated As of JDK 1.1, the preferred way translate a byte
  451. * stream in the local encoding into a character stream in Unicode is via
  452. * the <code>InputStreamReader</code> and <code>BufferedReader</code>
  453. * classes.
  454. *
  455. * @return a localized input stream.
  456. * @see java.io.InputStream
  457. * @see java.io.BufferedReader#BufferedReader(java.io.Reader)
  458. * @see java.io.InputStreamReader#InputStreamReader(java.io.InputStream)
  459. */
  460. public InputStream getLocalizedInputStream(InputStream in) {
  461. return in;
  462. }
  463. /**
  464. * Creates a localized version of an output stream. This method
  465. * takes an <code>OutputStream</code> and returns an
  466. * <code>OutputStream</code> equivalent to the argument in all respects
  467. * except that it is localized: as Unicode characters are written to
  468. * the stream, they are automatically converted to the local
  469. * character set.
  470. * <p>
  471. * If the argument is already a localized stream, it may be returned
  472. * as the result.
  473. *
  474. * @deprecated As of JDK 1.1, the preferred way to translate a
  475. * Unicode character stream into a byte stream in the local encoding is via
  476. * the <code>OutputStreamWriter</code>, <code>BufferedWriter</code>, and
  477. * <code>PrintWriter</code> classes.
  478. *
  479. * @return a localized output stream.
  480. * @see java.io.OutputStream
  481. * @see java.io.BufferedWriter#BufferedWriter(java.io.Writer)
  482. * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
  483. * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
  484. */
  485. public OutputStream getLocalizedOutputStream(OutputStream out) {
  486. return out;
  487. }
  488. }