(key, queue); refs.put(ref, res); return res; } }, , and so on, because they can disrupt the structure of the overall documentationhowever, they are usually safe to use within class and package documentation. To insert the character <, >, or & you should use <, >, or &, respectively. If you must have an @ at the beginning of a line, use @ otherwise, an @ is assumed to start a doc comment tag. tag, blocks of example code using <pre>, and so on. Not all tags need be processed by the javadoc tool by default; consult your tool documentation for details on what is needed to process which tags.Attribute Specification "The Java Developer's Almanac". The second uses quotes to enclose the name of the document. You might use these to direct readers to other documentation, such as the full specification. The @see forms that name a language entity (any of the above forms except the last two) can have a label following the entity. This label name will be the one used in the generated documentation instead of the entity's name. For example, @see #getName Attribute Namesnull. and HTML tags. These in-line tags are exceedingly convenient for writing about generic types.our license .Attr object defines an attribute as a * name/value pair, where the name is a String * and the value an arbitrary Object. * * @version 1.1 * @author Plato * @since 1.0 */ public class Attr { /** The attribute name. */ private final String name; /** The attribute value. */ private Object value = null; /** * Creates a new attribute with the given name and an * initial value of null. * @see Attr#Attr(String,Object) */ public Attr(String name) { this.name = name; } /** * Creates a new attribute with the given name and * initial value. * @see Attr#Attr(String) */ public Attr(String name, Object value) { this.name = name; this.value = value; } /** Returns this attribute's name. */ public String getName() { return name; } /** Returns this attribute's value. */ public Object getValue() { return value; } /** * Sets the value of this attribute. Changes the * value returned by calls to {@link #getValue}. * @param newValue The new value for the attribute. * @return The original value. * @see #getValue() */ public Object setValue(Object newValue) {name=value. */ public String toString() { return name + "='" + value + "'"; } }Formal Semantics inputs = file:///D|/1/0321349806/ch20lev1sec5.html (13 von 20) [11.01.2008 03:38:06](args.length); for (String arg : args) { fileIn = new FileInputStream(arg); bufIn = new BufferedInputStream(fileIn); inputs.add(bufIn); } Enumeration files = Collections.enumeration(inputs); in = new SequenceInputStream(files); } int ch; while ((ch = in.read()) != -1) System.out.write(ch); } // ... } Object writeReplace() throws ObjectStreamException Object readResolve() tHRows ObjectStreamException A mapping from keys to at most one value each. (Map does not extend Collection, A map whose keys are sorted (extends Map). Iterator<E> An interface for objects that return elements from a collection one at a time. This is the type of object returned by the method Iterable.iterator. ListIterator<E> An iterator for List objects that adds useful List-related methods. This is the type of object returned by List.listIterator. Iterable<E> An object that provides an Iterator and so can be used in an enhanced for statement. Although defined in the java.lang package, this is considered part of the collection framework because the vast majority of standard iterable types are collections. A hashtable implementation of Map. A very generally useful collection with relatively cheap lookup and insertion times. treeMap An implementation of SortedMap as a balanced binary tree to keep its elements An hashtable implementation of Map that references its keys with weak reference objects (see page 454). This is useful only in limited situations. Iterator snapshotIterator(Collection coll) { return new ArrayList(coll).iterator(); }. [2], but to do so would mean you wouldn't be able to assign the result to a variable of type Iterator. That would be a very annoying restriction. Many of the iterators defined in the java.util package are what is known as fail-fast iterators. Such iterators detect when a collection has been modified other than through the iterator itself, and fail quickly and cleanly by throwing an exceptiona ConcurrentModificationExceptionrather than risk performing an action whose behavior may be unsafe. can be implemented by any class whose objects can be sorted. The interface has a single method: public int compareTo(T other) interface has the method public int compare(T o1, T o2) T[] toArray(T[] dest) SortedSet copyHead(SortedSet set, T max) { SortedSet head = set.headSet(max); return new TreeSet(head); // contents from head } vertices = new ArrayList(); public void add(Point p) { vertices.add(p); } public void remove(Point p) { vertices.remove(p); } public int numVertices() { return vertices.size(); } // ... other methods ... } does not extend Collection because it has a contract that is different in important ways. The primary difference is that you do not add an element to a Mapyou add a key/value pair. A Map allows you to look up the value stored under a key. A given key (as defined by the equals method of the key) maps to one value or no values. A value can be mapped to by as many keys as you like. For example, you might use a map to store a mapping of a person's name to their address. If you have an address listed under a name, there will be exactly one in the map. If you have no mapping, there will be no address value for that name. Multiple people might share a single address, so the map might return the same value for two or more names. The basic methods of the Map interface are public int size() keySet() values()> enTRySet() defines methods for manipulating the entries in the map, as returned from the Map interface's entrySet method: subMap(K minKey, K maxKey) headMap(K maxKey) tailMap(K minKey) extends HashMap and refines the contract of HashMap by defining an order to the entries in the map. Iterating through the contents of a LinkedHashMap (either the entry set or the key map) getModifiers() { // ... } // ... rest of Field methods ... },V> is a special map that uses enum values as keys. All values in the map must come from the same enum type. Just like EnumSet the enum values are ordered by their natural order, and the iterator is weakly consistent. Suppose you were writing an application that dynamically builds and displays an on-line form, based on a description written in a structured format such as XML. Given the set of expected form elements as an enum enum FormElements { NAME, STREET, CITY, ZIP } keyType) map) map)> T min(Collection coll) T min(Collection coll, Comparator comp)> T max(Collection coll) T max(Collection coll, Comparator comp) Comparator reverseOrder() Comparator reverseOrder(Comparator comp) boolean addAll(Collection coll, T... elems) boolean replaceAll(List list, T oldVal, T newVal) void fill(List list, T elem) void copy(List dest, List src) List nCopies(int n, T elem)> void sort(List list) void sort(List list, Comparator comp) int binarySearch(List> list,T key) int binarySearch(List list, T key, Comparator comp)> void ensureKnown(List known, T value) { int indexAt = Collections.binarySearch(known, value); if (indexAt < 0) // not in the list -- insert it known.add(-(indexAt + 1), value); } Set singleton(T elem) List singletonList(T elem) Map singletonMap(K key, V value) List emptyList() Set emptySet() Map emptyMap() attrs() { return Collections. unmodifiableCollection(attrTable.values()); } interface, implemented by ConcurrentHashMap, defines a number of such methods: public V putIfAbsent(K key, V value) List asList(T... elems) abstract class is essentially an interface. It is analogous to the Map interface but uses the terms key and element instead of key and value. With two exceptions, each method in Dictionary has the same name as its analogous method in Map: get, put, remove, size, and isEmpty. The two exceptions are keys and elements. In Map, you get a Set of keys or values that you can iterate over or otherwise manipulate. In Dictionary, you can only get an Enumeration (iterator) for the keys and elements, using the keys and elements methods, respectively. The legacy collections did not contain a Set type, and so Dictionary could not be expressed in those terms. class is similar to the HashMap class, but implements the methods of Dictionary as well as (more recently) implementing the Map interface. All methods of Hashtable are synchronized, unlike HashMap. Beyond the methods inherited from Dictionary and Map, Hashtable adds the following methods and constructors: public Hashtable(). Standard Hashtable methods are used for almost all manipulation of a Properties object, but to get and set properties, you can use string-based methods. In addition to inherited methods, the following methods and constructors are provided: public Properties(), not Enumeration<String>. object whose run method defines the code to be marked as privileged. For example, your call to doPrivileged can look like the following: void someMethod() { // ...normal code here... AccessController.doPrivileged( new PrivilegedAction() { interface's single method run returns a T object. Another form of doPrivileged takes a PrivilegedExceptionAction object, whose run method also returns T, but which can throw any checked exception. For both of these methods there is a second overloaded form of doPrivileged that takes an AccessControlContext as an argument and uses that context to establish the permissions that the privileged code should run with. You should use doPrivileged with extreme care and ensure that your privileged sections of code are no longer than necessary and that they perform only actions you fully control. For example, it would be an extreme security risk for a method with, say, all I/O permissions, to accept a Runnable argument and invoke its run method within a privileged section of code, unless you wouldn't mind if that method removed all the files on your disk. Power corrupts. Absolute power is kind of neat. John Lehman, U.S. Secretary of the Navy, 19811987 sortedStrings; private Collator collator; CollationKeySorting(Collator collator) { this.collator = collator; sortedStrings = new TreeMap(); } void add(String str) { sortedStrings.put( collator.getCollationKey(str), str); } Iterator<String> strings() { return sortedStrings.values().iterator(); } } or tag is found in a web page's HTML, the browser downloads the code for the named class from a URL, creates an object of that class, creates a region on the web page for that object to control, and then invokes the object's init methodoften creating a THReadGroup and THRead just for this applet. As the applet runs, it can download other classes from the server as needed. Applets are usually run in a tightly secured "sandbox" in which potentially dangerous operations (such as file access, network access, and running local programs) are restricted by the security policy. The method init is one of four lifecycle methods defined for the applet in the Applet class. After init is called, start is called, which tells the applet that it is active and should perform its function. If the browser decides that the applet is no longer of interest to the user, for example, the user leaves the page the applet was on, the applet's stop method is invoked to tell it to stop what it was doing. If the user returns to the applet's page the browser may invoke start again to tell the applet to recommenceso the applet can cycle through a stopstart sequence as the user presses the "Back" and "Forward" buttons (or their equivalents) to visit and leave the page. When the browser decides that the applet is no longer of interest (perhaps because the user has moved a number of pages away) the applet's destroy method is invoked to free up any resources used by the applet. If the applet's page is now revisited the lifecycle will recommence with init being called again. The browser ultimately defines the lifecycle of an applet and may choose to invoke destroy immediately after stop when the user leaves the page. Whether or not an applet class is unloaded and reloaded between visits to the applet is again a feature of the browser. These lifecycle methods are typically overridden by applet classes. For example, if an applet uses a thread to do its work, init would typically create the thread; start would invoke the thread's start method the first time and ask it to continue execution on subsequent invocations; stop could ask the thread to pause to prevent it from consuming resources while the page is not visible; and destroy could interrupt the thread because the thread would no longer be needed. An applet can get parameters from a <param> tag to customize its behavior. It might get colors, fonts, or the URL of an image to display. Applets usually run in a highly constrained security environment to protect your computer and network from unwelcome inspection or invasion by a hostile applet. This means that certain conveniences, such as a local scratch disk, may not be available by default. You can grant permission to perform particular actions to individual applets by specifying an appropriate security policy. The applet model is a good example of how the Java platform provides power. The fact that the same code runs on all systems in the same way allows a single piece of code (an applet) to run in a variety of browsers on a variety of windowing systems running on a larger variety of operating systems. The portability of Java bytecodes allows you to execute part of your application on the server and another part on the client system via downloaded code, whichever is appropriate. It is the same platform on both sides: the Java virtual machine. The ability to move code from one place to another and execute it in a secure environment enables new ways of thinking about where to execute what part of your design.
