1 /* System.java -- useful methods to interface with the system
2 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007
3 Free Software Foundation, Inc.
5 This file is part of GNU Classpath.
7 GNU Classpath is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2, or (at your option)
12 GNU Classpath is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Classpath; see the file COPYING. If not, write to the
19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
22 Linking this library statically or dynamically with other modules is
23 making a combined work based on this library. Thus, the terms and
24 conditions of the GNU General Public License cover the whole
27 As a special exception, the copyright holders of this library give you
28 permission to link this library with independent modules to produce an
29 executable, regardless of the license terms of these independent
30 modules, and to copy and distribute the resulting executable under
31 terms of your choice, provided that you also meet, for each linked
32 independent module, the terms and conditions of the license of that
33 module. An independent module is a module which is not derived from
34 or based on this library. If you modify this library, you may extend
35 this exception to your version of the library, but you are not
36 obligated to do so. If you do not wish to do so, delete this
37 exception statement from your version. */
42 import gnu.classpath.SystemProperties;
43 import gnu.classpath.VMStackWalker;
45 import java.io.IOException;
46 import java.io.InputStream;
47 import java.io.PrintStream;
48 import java.nio.channels.Channel;
49 import java.nio.channels.spi.SelectorProvider;
50 import java.util.AbstractCollection;
51 import java.util.Collection;
52 import java.util.Collections;
53 import java.util.HashMap;
54 import java.util.Iterator;
55 import java.util.List;
58 import java.util.Properties;
59 import java.util.PropertyPermission;
62 * System represents system-wide resources; things that represent the
63 * general environment. As such, all methods are static.
66 * @author Eric Blake (ebb9@email.byu.edu)
68 * @status still missing 1.4 functionality
70 public final class System
72 // WARNING: System is a CORE class in the bootstrap cycle. See the comments
73 // in vm/reference/java/lang/Runtime for implications of this fact.
76 * The standard InputStream. This is assigned at startup and starts its
77 * life perfectly valid. Although it is marked final, you can change it
78 * using {@link #setIn(InputStream)} through some hefty VM magic.
80 * <p>This corresponds to the C stdin and C++ cin variables, which
81 * typically input from the keyboard, but may be used to pipe input from
82 * other processes or files. That should all be transparent to you,
85 public static final InputStream in = VMSystem.makeStandardInputStream();
88 * The standard output PrintStream. This is assigned at startup and
89 * starts its life perfectly valid. Although it is marked final, you can
90 * change it using {@link #setOut(PrintStream)} through some hefty VM magic.
92 * <p>This corresponds to the C stdout and C++ cout variables, which
93 * typically output normal messages to the screen, but may be used to pipe
94 * output to other processes or files. That should all be transparent to
97 public static final PrintStream out = VMSystem.makeStandardOutputStream();
100 * The standard output PrintStream. This is assigned at startup and
101 * starts its life perfectly valid. Although it is marked final, you can
102 * change it using {@link #setErr(PrintStream)} through some hefty VM magic.
104 * <p>This corresponds to the C stderr and C++ cerr variables, which
105 * typically output error messages to the screen, but may be used to pipe
106 * output to other processes or files. That should all be transparent to
109 public static final PrintStream err = VMSystem.makeStandardErrorStream();
112 * A cached copy of the environment variable map.
114 private static Map<String,String> environmentMap;
117 * This class is uninstantiable.
124 * Set {@link #in} to a new InputStream. This uses some VM magic to change
125 * a "final" variable, so naturally there is a security check,
126 * <code>RuntimePermission("setIO")</code>.
128 * @param in the new InputStream
129 * @throws SecurityException if permission is denied
132 public static void setIn(InputStream in)
134 SecurityManager sm = SecurityManager.current; // Be thread-safe.
136 sm.checkPermission(new RuntimePermission("setIO"));
142 * Set {@link #out} to a new PrintStream. This uses some VM magic to change
143 * a "final" variable, so naturally there is a security check,
144 * <code>RuntimePermission("setIO")</code>.
146 * @param out the new PrintStream
147 * @throws SecurityException if permission is denied
150 public static void setOut(PrintStream out)
152 SecurityManager sm = SecurityManager.current; // Be thread-safe.
154 sm.checkPermission(new RuntimePermission("setIO"));
155 VMSystem.setOut(out);
159 * Set {@link #err} to a new PrintStream. This uses some VM magic to change
160 * a "final" variable, so naturally there is a security check,
161 * <code>RuntimePermission("setIO")</code>.
163 * @param err the new PrintStream
164 * @throws SecurityException if permission is denied
167 public static void setErr(PrintStream err)
169 SecurityManager sm = SecurityManager.current; // Be thread-safe.
171 sm.checkPermission(new RuntimePermission("setIO"));
172 VMSystem.setErr(err);
176 * Set the current SecurityManager. If a security manager already exists,
177 * then <code>RuntimePermission("setSecurityManager")</code> is checked
178 * first. Since this permission is denied by the default security manager,
179 * setting the security manager is often an irreversible action.
181 * <STRONG>Spec Note:</STRONG> Don't ask me, I didn't write it. It looks
182 * pretty vulnerable; whoever gets to the gate first gets to set the policy.
183 * There is probably some way to set the original security manager as a
184 * command line argument to the VM, but I don't know it.
186 * @param sm the new SecurityManager
187 * @throws SecurityException if permission is denied
189 public static synchronized void setSecurityManager(SecurityManager sm)
191 // Implementation note: the field lives in SecurityManager because of
192 // bootstrap initialization issues. This method is synchronized so that
193 // no other thread changes it to null before this thread makes the change.
194 if (SecurityManager.current != null)
195 SecurityManager.current.checkPermission
196 (new RuntimePermission("setSecurityManager"));
198 // java.security.Security's class initialiser loads and parses the
199 // policy files. If it hasn't been run already it will be run
200 // during the first permission check. That initialisation will
201 // fail if a very restrictive security manager is in force, so we
203 if (SecurityManager.current == null)
207 Class.forName("java.security.Security");
209 catch (ClassNotFoundException e)
214 SecurityManager.current = sm;
218 * Get the current SecurityManager. If the SecurityManager has not been
219 * set yet, then this method returns null.
221 * @return the current SecurityManager, or null
223 public static SecurityManager getSecurityManager()
225 return SecurityManager.current;
229 * Get the current time, measured in the number of milliseconds from the
230 * beginning of Jan. 1, 1970. This is gathered from the system clock, with
231 * any attendant incorrectness (it may be timezone dependent).
233 * @return the current time
234 * @see java.util.Date
236 public static long currentTimeMillis()
238 return VMSystem.currentTimeMillis();
243 * Returns the current value of a nanosecond-precise system timer.
244 * The value of the timer is an offset relative to some arbitrary fixed
245 * time, which may be in the future (making the value negative). This
246 * method is useful for timing events where nanosecond precision is
247 * required. This is achieved by calling this method before and after the
248 * event, and taking the difference betweent the two times:
251 * <code>long startTime = System.nanoTime();</code><br />
252 * <code>... <emph>event code</emph> ...</code><br />
253 * <code>long endTime = System.nanoTime();</code><br />
254 * <code>long duration = endTime - startTime;</code><br />
257 * Note that the value is only nanosecond-precise, and not accurate; there
258 * is no guarantee that the difference between two values is really a
259 * nanosecond. Also, the value is prone to overflow if the offset
263 * @return the time of a system timer in nanoseconds.
266 public static long nanoTime()
268 return VMSystem.nanoTime();
272 * Copy one array onto another from <code>src[srcStart]</code> ...
273 * <code>src[srcStart+len-1]</code> to <code>dest[destStart]</code> ...
274 * <code>dest[destStart+len-1]</code>. First, the arguments are validated:
275 * neither array may be null, they must be of compatible types, and the
276 * start and length must fit within both arrays. Then the copying starts,
277 * and proceeds through increasing slots. If src and dest are the same
278 * array, this will appear to copy the data to a temporary location first.
279 * An ArrayStoreException in the middle of copying will leave earlier
280 * elements copied, but later elements unchanged.
282 * @param src the array to copy elements from
283 * @param srcStart the starting position in src
284 * @param dest the array to copy elements to
285 * @param destStart the starting position in dest
286 * @param len the number of elements to copy
287 * @throws NullPointerException if src or dest is null
288 * @throws ArrayStoreException if src or dest is not an array, if they are
289 * not compatible array types, or if an incompatible runtime type
291 * @throws IndexOutOfBoundsException if len is negative, or if the start or
292 * end copy position in either array is out of bounds
294 public static void arraycopy(Object src, int srcStart,
295 Object dest, int destStart, int len)
297 VMSystem.arraycopy(src, srcStart, dest, destStart, len);
301 * Get a hash code computed by the VM for the Object. This hash code will
302 * be the same as Object's hashCode() method. It is usually some
303 * convolution of the pointer to the Object internal to the VM. It
304 * follows standard hash code rules, in that it will remain the same for a
305 * given Object for the lifetime of that Object.
307 * @param o the Object to get the hash code for
308 * @return the VM-dependent hash code for this Object
311 public static int identityHashCode(Object o)
313 return VMSystem.identityHashCode(o);
317 * Get all the system properties at once. A security check may be performed,
318 * <code>checkPropertiesAccess</code>. Note that a security manager may
319 * allow getting a single property, but not the entire group.
321 * <p>The required properties include:
323 * <dt>java.version</dt> <dd>Java version number</dd>
324 * <dt>java.vendor</dt> <dd>Java vendor specific string</dd>
325 * <dt>java.vendor.url</dt> <dd>Java vendor URL</dd>
326 * <dt>java.home</dt> <dd>Java installation directory</dd>
327 * <dt>java.vm.specification.version</dt> <dd>VM Spec version</dd>
328 * <dt>java.vm.specification.vendor</dt> <dd>VM Spec vendor</dd>
329 * <dt>java.vm.specification.name</dt> <dd>VM Spec name</dd>
330 * <dt>java.vm.version</dt> <dd>VM implementation version</dd>
331 * <dt>java.vm.vendor</dt> <dd>VM implementation vendor</dd>
332 * <dt>java.vm.name</dt> <dd>VM implementation name</dd>
333 * <dt>java.specification.version</dt> <dd>Java Runtime Environment version</dd>
334 * <dt>java.specification.vendor</dt> <dd>Java Runtime Environment vendor</dd>
335 * <dt>java.specification.name</dt> <dd>Java Runtime Environment name</dd>
336 * <dt>java.class.version</dt> <dd>Java class version number</dd>
337 * <dt>java.class.path</dt> <dd>Java classpath</dd>
338 * <dt>java.library.path</dt> <dd>Path for finding Java libraries</dd>
339 * <dt>java.io.tmpdir</dt> <dd>Default temp file path</dd>
340 * <dt>java.compiler</dt> <dd>Name of JIT to use</dd>
341 * <dt>java.ext.dirs</dt> <dd>Java extension path</dd>
342 * <dt>os.name</dt> <dd>Operating System Name</dd>
343 * <dt>os.arch</dt> <dd>Operating System Architecture</dd>
344 * <dt>os.version</dt> <dd>Operating System Version</dd>
345 * <dt>file.separator</dt> <dd>File separator ("/" on Unix)</dd>
346 * <dt>path.separator</dt> <dd>Path separator (":" on Unix)</dd>
347 * <dt>line.separator</dt> <dd>Line separator ("\n" on Unix)</dd>
348 * <dt>user.name</dt> <dd>User account name</dd>
349 * <dt>user.home</dt> <dd>User home directory</dd>
350 * <dt>user.dir</dt> <dd>User's current working directory</dd>
353 * In addition, gnu defines several other properties, where ? stands for
354 * each character in '0' through '9':
356 * <dt>gnu.classpath.home</dt> <dd>Path to the classpath libraries.</dd>
357 * <dt>gnu.classpath.version</dt> <dd>Version of the classpath libraries.</dd>
358 * <dt>gnu.classpath.vm.shortname</dt> <dd>Succinct version of the VM name;
359 * used for finding property files in file system</dd>
360 * <dt>gnu.classpath.home.url</dt> <dd> Base URL; used for finding
361 * property files in file system</dd>
362 * <dt>gnu.cpu.endian</dt> <dd>big or little</dd>
363 * <dt>gnu.java.io.encoding_scheme_alias.iso-8859-?</dt> <dd>8859_?</dd>
364 * <dt>gnu.java.io.encoding_scheme_alias.iso8859_?</dt> <dd>8859_?</dd>
365 * <dt>gnu.java.io.encoding_scheme_alias.iso-latin-_?</dt> <dd>8859_?</dd>
366 * <dt>gnu.java.io.encoding_scheme_alias.latin?</dt> <dd>8859_?</dd>
367 * <dt>gnu.java.io.encoding_scheme_alias.utf-8</dt> <dd>UTF8</dd>
368 * <dt>gnu.java.util.zoneinfo.dir</dt> <dd>Root of zoneinfo tree</dd>
369 * <dt>gnu.javax.print.server</dt> <dd>Hostname of external CUPS server.</dd>
372 * @return the system properties, will never be null
373 * @throws SecurityException if permission is denied
375 public static Properties getProperties()
377 SecurityManager sm = SecurityManager.current; // Be thread-safe.
379 sm.checkPropertiesAccess();
380 return SystemProperties.getProperties();
384 * Set all the system properties at once. A security check may be performed,
385 * <code>checkPropertiesAccess</code>. Note that a security manager may
386 * allow setting a single property, but not the entire group. An argument
387 * of null resets the properties to the startup default.
389 * @param properties the new set of system properties
390 * @throws SecurityException if permission is denied
392 public static void setProperties(Properties properties)
394 SecurityManager sm = SecurityManager.current; // Be thread-safe.
396 sm.checkPropertiesAccess();
397 SystemProperties.setProperties(properties);
401 * Get a single system property by name. A security check may be performed,
402 * <code>checkPropertyAccess(key)</code>.
404 * @param key the name of the system property to get
405 * @return the property, or null if not found
406 * @throws SecurityException if permission is denied
407 * @throws NullPointerException if key is null
408 * @throws IllegalArgumentException if key is ""
410 public static String getProperty(String key)
412 SecurityManager sm = SecurityManager.current; // Be thread-safe.
414 sm.checkPropertyAccess(key);
415 if (key.length() == 0)
416 throw new IllegalArgumentException("key can't be empty");
417 return SystemProperties.getProperty(key);
421 * Get a single system property by name. A security check may be performed,
422 * <code>checkPropertyAccess(key)</code>.
424 * @param key the name of the system property to get
425 * @param def the default
426 * @return the property, or def if not found
427 * @throws SecurityException if permission is denied
428 * @throws NullPointerException if key is null
429 * @throws IllegalArgumentException if key is ""
431 public static String getProperty(String key, String def)
433 SecurityManager sm = SecurityManager.current; // Be thread-safe.
435 sm.checkPropertyAccess(key);
436 // This handles both the null pointer exception and the illegal
437 // argument exception.
438 if (key.length() == 0)
439 throw new IllegalArgumentException("key can't be empty");
440 return SystemProperties.getProperty(key, def);
444 * Set a single system property by name. A security check may be performed,
445 * <code>checkPropertyAccess(key, "write")</code>.
447 * @param key the name of the system property to set
448 * @param value the new value
449 * @return the previous value, or null
450 * @throws SecurityException if permission is denied
451 * @throws NullPointerException if key is null
452 * @throws IllegalArgumentException if key is ""
455 public static String setProperty(String key, String value)
457 SecurityManager sm = SecurityManager.current; // Be thread-safe.
459 sm.checkPermission(new PropertyPermission(key, "write"));
460 // This handles both the null pointer exception and the illegal
461 // argument exception.
462 if (key.length() == 0)
463 throw new IllegalArgumentException("key can't be empty");
464 return SystemProperties.setProperty(key, value);
468 * Remove a single system property by name. A security check may be
469 * performed, <code>checkPropertyAccess(key, "write")</code>.
471 * @param key the name of the system property to remove
472 * @return the previous value, or null
473 * @throws SecurityException if permission is denied
474 * @throws NullPointerException if key is null
475 * @throws IllegalArgumentException if key is ""
478 public static String clearProperty(String key)
480 SecurityManager sm = SecurityManager.current; // Be thread-safe.
482 sm.checkPermission(new PropertyPermission(key, "write"));
483 // This handles both the null pointer exception and the illegal
484 // argument exception.
485 if (key.length() == 0)
486 throw new IllegalArgumentException("key can't be empty");
487 return SystemProperties.remove(key);
491 * Gets the value of an environment variable.
493 * @param name the name of the environment variable
494 * @return the string value of the variable or null when the
495 * environment variable is not defined.
496 * @throws NullPointerException
497 * @throws SecurityException if permission is denied
499 * @specnote This method was deprecated in some JDK releases, but
500 * was restored in 1.5.
502 public static String getenv(String name)
505 throw new NullPointerException();
506 SecurityManager sm = SecurityManager.current; // Be thread-safe.
508 sm.checkPermission(new RuntimePermission("getenv." + name));
509 return VMSystem.getenv(name);
514 * Returns an unmodifiable view of the system environment variables.
515 * If the underlying system does not support environment variables,
516 * an empty map is returned.
519 * The returned map is read-only and does not accept queries using
520 * null keys or values, or those of a type other than <code>String</code>.
521 * Attempts to modify the map will throw an
522 * <code>UnsupportedOperationException</code>, while attempts
523 * to pass in a null value will throw a
524 * <code>NullPointerException</code>. Types other than <code>String</code>
525 * throw a <code>ClassCastException</code>.
528 * As the returned map is generated using data from the underlying
529 * platform, it may not comply with the <code>equals()</code>
530 * and <code>hashCode()</code> contracts. It is also likely that
531 * the keys of this map will be case-sensitive.
534 * Use of this method may require a security check for the
535 * RuntimePermission "getenv.*".
538 * @return a map of the system environment variables.
539 * @throws SecurityException if the checkPermission method of
540 * an installed security manager prevents access to
541 * the system environment variables.
544 public static Map<String, String> getenv()
546 SecurityManager sm = SecurityManager.current; // Be thread-safe.
548 sm.checkPermission(new RuntimePermission("getenv.*"));
550 if (environmentMap == null)
552 Map<String,String> variables = new EnvironmentMap();
553 List<String> environ = (List<String>)VMSystem.environ();
554 for (String envEntry : environ)
556 // avoid broken and null entries
557 if (envEntry != null && !envEntry.endsWith("="))
559 // it's perfectly legal that some entries may be in the form
560 // key=value=value=value
561 int equalSignIndex = envEntry.indexOf('=');
562 String key = envEntry.substring(0, equalSignIndex);
563 String value = envEntry.substring(equalSignIndex + 1);
564 variables.put(key, value);
568 environmentMap = Collections.unmodifiableMap(variables);
571 return environmentMap;
575 * Terminate the Virtual Machine. This just calls
576 * <code>Runtime.getRuntime().exit(status)</code>, and never returns.
577 * Obviously, a security check is in order, <code>checkExit</code>.
579 * @param status the exit status; by convention non-zero is abnormal
580 * @throws SecurityException if permission is denied
581 * @see Runtime#exit(int)
583 public static void exit(int status)
585 Runtime.getRuntime().exit(status);
589 * Calls the garbage collector. This is only a hint, and it is up to the
590 * implementation what this hint suggests, but it usually causes a
591 * best-effort attempt to reclaim unused memory from discarded objects.
592 * This calls <code>Runtime.getRuntime().gc()</code>.
596 public static void gc()
598 Runtime.getRuntime().gc();
602 * Runs object finalization on pending objects. This is only a hint, and
603 * it is up to the implementation what this hint suggests, but it usually
604 * causes a best-effort attempt to run finalizers on all objects ready
605 * to be reclaimed. This calls
606 * <code>Runtime.getRuntime().runFinalization()</code>.
608 * @see Runtime#runFinalization()
610 public static void runFinalization()
612 Runtime.getRuntime().runFinalization();
616 * Tell the Runtime whether to run finalization before exiting the
617 * JVM. This is inherently unsafe in multi-threaded applications,
618 * since it can force initialization on objects which are still in use
619 * by live threads, leading to deadlock; therefore this is disabled by
620 * default. There may be a security check, <code>checkExit(0)</code>. This
621 * calls <code>Runtime.runFinalizersOnExit()</code>.
623 * @param finalizeOnExit whether to run finalizers on exit
624 * @throws SecurityException if permission is denied
625 * @see Runtime#runFinalizersOnExit(boolean)
627 * @deprecated never rely on finalizers to do a clean, thread-safe,
628 * mop-up from your code
630 public static void runFinalizersOnExit(boolean finalizeOnExit)
632 Runtime.runFinalizersOnExit(finalizeOnExit);
636 * Load a code file using its explicit system-dependent filename. A security
637 * check may be performed, <code>checkLink</code>. This just calls
638 * <code>Runtime.getRuntime().load(filename)</code>.
641 * The library is loaded using the class loader associated with the
642 * class associated with the invoking method.
644 * @param filename the code file to load
645 * @throws SecurityException if permission is denied
646 * @throws UnsatisfiedLinkError if the file cannot be loaded
647 * @see Runtime#load(String)
649 public static void load(String filename)
651 Runtime.getRuntime().load(filename, VMStackWalker.getCallingClassLoader());
655 * Load a library using its explicit system-dependent filename. A security
656 * check may be performed, <code>checkLink</code>. This just calls
657 * <code>Runtime.getRuntime().load(filename)</code>.
660 * The library is loaded using the class loader associated with the
661 * class associated with the invoking method.
663 * @param libname the library file to load
664 * @throws SecurityException if permission is denied
665 * @throws UnsatisfiedLinkError if the file cannot be loaded
666 * @see Runtime#load(String)
668 public static void loadLibrary(String libname)
670 Runtime.getRuntime().loadLibrary(libname,
671 VMStackWalker.getCallingClassLoader());
675 * Convert a library name to its platform-specific variant.
677 * @param libname the library name, as used in <code>loadLibrary</code>
678 * @return the platform-specific mangling of the name
681 public static String mapLibraryName(String libname)
683 return VMRuntime.mapLibraryName(libname);
687 * Returns the inherited channel of the VM.
689 * This wraps the inheritedChannel() call of the system's default
690 * {@link SelectorProvider}.
692 * @return the inherited channel of the VM
694 * @throws IOException If an I/O error occurs
695 * @throws SecurityException If an installed security manager denies access
696 * to RuntimePermission("inheritedChannel")
700 public static Channel inheritedChannel()
703 return SelectorProvider.provider().inheritedChannel();
707 * This is a specialised <code>Collection</code>, providing
708 * the necessary provisions for the collections used by the
709 * environment variable map. Namely, it prevents
710 * querying anything but <code>String</code>s.
712 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
714 private static class EnvironmentCollection
715 extends AbstractCollection<String>
719 * The wrapped collection.
721 protected Collection<String> c;
724 * Constructs a new environment collection, which
725 * wraps the elements of the supplied collection.
727 * @param coll the collection to use as a base for
730 public EnvironmentCollection(Collection<String> coll)
736 * Blocks queries containing a null object or an object which
737 * isn't of type <code>String</code>. All other queries
738 * are forwarded to the underlying collection.
740 * @param obj the object to look for.
741 * @return true if the object exists in the collection.
742 * @throws NullPointerException if the specified object is null.
743 * @throws ClassCastException if the specified object is not a String.
745 public boolean contains(Object obj)
749 NullPointerException("This collection does not support " +
751 if (!(obj instanceof String))
753 ClassCastException("This collection only supports Strings.");
754 return c.contains(obj);
758 * Blocks queries where the collection contains a null object or
759 * an object which isn't of type <code>String</code>. All other
760 * queries are forwarded to the underlying collection.
762 * @param coll the collection of objects to look for.
763 * @return true if the collection contains all elements in the collection.
764 * @throws NullPointerException if the collection is null.
765 * @throws NullPointerException if any collection entry is null.
766 * @throws ClassCastException if any collection entry is not a String.
768 public boolean containsAll(Collection<?> coll)
774 NullPointerException("This collection does not support " +
776 if (!(o instanceof String))
778 ClassCastException("This collection only supports Strings.");
780 return c.containsAll(coll);
784 * This returns an iterator over the map elements, with the
785 * same provisions as for the collection and underlying map.
787 * @return an iterator over the map elements.
789 public Iterator<String> iterator()
795 * Blocks the removal of elements from the collection.
797 * @return true if the removal was sucessful.
798 * @throws NullPointerException if the collection is null.
799 * @throws NullPointerException if any collection entry is null.
800 * @throws ClassCastException if any collection entry is not a String.
802 public boolean remove(Object key)
806 NullPointerException("This collection does not support " +
808 if (!(key instanceof String))
810 ClassCastException("This collection only supports Strings.");
811 return c.contains(key);
815 * Blocks the removal of all elements in the specified
816 * collection from the collection.
818 * @param coll the collection of elements to remove.
819 * @return true if the elements were removed.
820 * @throws NullPointerException if the collection is null.
821 * @throws NullPointerException if any collection entry is null.
822 * @throws ClassCastException if any collection entry is not a String.
824 public boolean removeAll(Collection<?> coll)
830 NullPointerException("This collection does not support " +
832 if (!(o instanceof String))
834 ClassCastException("This collection only supports Strings.");
836 return c.removeAll(coll);
840 * Blocks the retention of all elements in the specified
841 * collection from the collection.
843 * @param coll the collection of elements to retain.
844 * @return true if the other elements were removed.
845 * @throws NullPointerException if the collection is null.
846 * @throws NullPointerException if any collection entry is null.
847 * @throws ClassCastException if any collection entry is not a String.
849 public boolean retainAll(Collection<?> coll)
855 NullPointerException("This collection does not support " +
857 if (!(o instanceof String))
859 ClassCastException("This collection only supports Strings.");
861 return c.containsAll(coll);
865 * This simply calls the same method on the wrapped
868 * @return the size of the underlying collection.
875 } // class EnvironmentCollection<String>
878 * This is a specialised <code>HashMap</code>, which
879 * prevents the addition or querying of anything other than
880 * <code>String</code> objects.
882 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
884 static class EnvironmentMap
885 extends HashMap<String,String>
889 * Cache the entry set.
891 private transient Set<Map.Entry<String,String>> entries;
896 private transient Set<String> keys;
899 * Cache the value collection.
901 private transient Collection<String> values;
904 * Constructs a new empty <code>EnvironmentMap</code>.
912 * Constructs a new <code>EnvironmentMap</code> containing
913 * the contents of the specified map.
915 * @param m the map to be added to this.
916 * @throws NullPointerException if a key or value is null.
917 * @throws ClassCastException if a key or value is not a String.
919 EnvironmentMap(Map<String,String> m)
925 * Blocks queries containing a null key or one which is not
926 * of type <code>String</code>. All other queries
927 * are forwarded to the superclass.
929 * @param key the key to look for in the map.
930 * @return true if the key exists in the map.
931 * @throws NullPointerException if the specified key is null.
933 public boolean containsKey(Object key)
937 NullPointerException("This map does not support null keys.");
938 if (!(key instanceof String))
940 ClassCastException("This map only allows queries using Strings.");
941 return super.containsKey(key);
945 * Blocks queries using a null or non-<code>String</code> value.
946 * All other queries are forwarded to the superclass.
948 * @param value the value to look for in the map.
949 * @return true if the value exists in the map.
950 * @throws NullPointerException if the specified value is null.
952 public boolean containsValue(Object value)
956 NullPointerException("This map does not support null values.");
957 if (!(value instanceof String))
959 ClassCastException("This map only allows queries using Strings.");
960 return super.containsValue(value);
964 * Returns a set view of the map entries, with the same
965 * provisions as for the underlying map.
967 * @return a set containing the map entries.
969 public Set<Map.Entry<String,String>> entrySet()
972 entries = super.entrySet();
977 * Blocks queries containing a null or non-<code>String</code> key.
978 * All other queries are passed on to the superclass.
980 * @param key the key to retrieve the value for.
981 * @return the value associated with the given key.
982 * @throws NullPointerException if the specified key is null.
983 * @throws ClassCastException if the specified key is not a String.
985 public String get(Object key)
989 NullPointerException("This map does not support null keys.");
990 if (!(key instanceof String))
992 ClassCastException("This map only allows queries using Strings.");
993 return super.get(key);
997 * Returns a set view of the keys, with the same
998 * provisions as for the underlying map.
1000 * @return a set containing the keys.
1002 public Set<String> keySet()
1005 keys = new EnvironmentSet(super.keySet());
1010 * Associates the given key to the given value. If the
1011 * map already contains the key, its value is replaced.
1012 * The map does not accept null keys or values, or keys
1013 * and values not of type {@link String}.
1015 * @param key the key to map.
1016 * @param value the value to be mapped.
1017 * @return the previous value of the key, or null if there was no mapping
1018 * @throws NullPointerException if a key or value is null.
1019 * @throws ClassCastException if a key or value is not a String.
1021 public String put(String key, String value)
1024 throw new NullPointerException("A new key is null.");
1026 throw new NullPointerException("A new value is null.");
1027 if (!(key instanceof String))
1028 throw new ClassCastException("A new key is not a String.");
1029 if (!(value instanceof String))
1030 throw new ClassCastException("A new value is not a String.");
1031 return super.put(key, value);
1035 * Removes a key-value pair from the map. The queried key may not
1036 * be null or of a type other than a <code>String</code>.
1038 * @param key the key of the entry to remove.
1039 * @return the removed value.
1040 * @throws NullPointerException if the specified key is null.
1041 * @throws ClassCastException if the specified key is not a String.
1043 public String remove(Object key)
1047 NullPointerException("This map does not support null keys.");
1048 if (!(key instanceof String))
1050 ClassCastException("This map only allows queries using Strings.");
1051 return super.remove(key);
1055 * Returns a collection view of the values, with the same
1056 * provisions as for the underlying map.
1058 * @return a collection containing the values.
1060 public Collection<String> values()
1063 values = new EnvironmentCollection(super.values());
1070 * This is a specialised <code>Set</code>, providing
1071 * the necessary provisions for the collections used by the
1072 * environment variable map. Namely, it prevents
1073 * modifications and the use of queries with null
1074 * or non-<code>String</code> values.
1076 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
1078 private static class EnvironmentSet
1079 extends EnvironmentCollection
1080 implements Set<String>
1084 * Constructs a new environment set, which
1085 * wraps the elements of the supplied set.
1087 * @param set the set to use as a base for
1090 public EnvironmentSet(Set<String> set)
1096 * This simply calls the same method on the wrapped
1099 * @param obj the object to compare with.
1100 * @return true if the two objects are equal.
1102 public boolean equals(Object obj)
1104 return c.equals(obj);
1108 * This simply calls the same method on the wrapped
1111 * @return the hashcode of the collection.
1113 public int hashCode()
1115 return c.hashCode();
1118 } // class EnvironmentSet<String>