NIO APIs: Beta 3 Changes

New I/O APIs

This document describes how the NIO APIs in the Beta 3 release of J2SE v 1.4 differ from those in Beta 2. The most significant change is a redesign of the java.nio.charset package to address the performance problems of the original design. A number of small adjustments have been made to the java.util.regex package to bring it into nearly perfect alignment with the regular-expression language implemented in Perl 5. The remaining changes are in response to feedback received from the community and issues raised within the Expert Group.

The changes are summarized by area:

• Buffers
• Files
• Selectors, selectable channels, and selection keys
• Charsets
• Regular expressions
• Other

Buffers

• Added hasArray, array, and arrayOffset methods to all of the concrete buffer classes. (4503732)

• Revised the specification of the MappedByteBuffer class to say that an attempt to access an inaccessible region of a mapped byte buffer will either return an arbitrary value (if reading) or have no visible effect (if writing); it will also cause an unspecified exception to be thrown either at the time of access or at some later time. (This is consistent with Sun's current implementation.)

• Changed the static CharBuffer.wrap(String,int,int) and CharBuffer.wrap(String) methods to take a CharSequence rather than a String.

• Added the ByteOrder.nativeOrder method, which is useful when setting up direct buffers that will be manipulated by native code.

• Added order methods to each of the non-byte buffer classes (CharBuffer, ShortBuffer, IntBuffer, LongBuffer, FloatBuffer, and DoubleBuffer).

Files

• Added the mode characters "s" and "d" to the RandomAccessFile constructors to allow the specification, at file-open time, of synchronous writes or synchronous-data writes.

• Replaced the integer FileChannel.MAP_{RO,RW,COW} constants with the typesafe enumeration FileChannel.MapMode.

Selectors, selectable channels, and selection keys

• Restricted the socket() methods in the socket-channel classes to return objects that do not not define any more public methods than those declared in the corresponding java.net socket class. (4497675)

• Added API to allow the retrieval of the provider that created a channel or a selector: Added provider arguments to the protected constructors of the DatagramChannel, ServerSocketChannel, SocketChannel, Pipe.SourceChannel, Pipe.SinkChannel, AbstractSelectableChannel, and AbstractSelector classes; added provider() methods to the SelectableChannel, AbstractSelectableChannel, Selector, and AbstractSelector classes. These changes are required for writing provider-independent channel adaptors. (4497675)

• Changed the ServerSocketChannel.accept method to return a SocketChannel rather than a Socket. The fact that it returned a socket was confusing to many developers. (4497675)

• Removed the extraneous DatagramChannel.open(int port) method and the int argument to the SelectorProvider.openDatagramChannel method. (4497675)

• Revised the specification of SelectionKey to say that the attach and attachment methods are thread-safe.

• Added a three-argument register method to SelectableChannel so that an initial (or new) attachment can be specified when registering a channel with a selector.

• Removed direct support of timeouts from all socket channels, and removed TimeoutException. Timeouts are still supported via the associated socket adaptors, which implement timeouts with per-thread cached selectors. (4487459)

• Changed the connect method of DatagramChannel to be void rather than return a boolean since datagram channels don't support (or even need) non-blocking connect operations.

• Removed the shutdown methods from SocketChannel, since they are already provided (though in slightly different form) by the java.net.Socket class.

• Added isOpen methods to Selector and AbstractSelector. Added close and implCloseSelector methods to AbstractSelector.

• Added a static open(SocketAddress remote) convenience method to SocketChannel.

• Clarified the specification of the Selector.wakeup method to say that the wakeup state is cleared by any selection operation, including an invocation of selectNow.

Charsets

• Defined the CoderResult class, a typesafe enumeration for reporting coder results. The encode and decode methods, as well as the flush methods, now return instances of this class rather than throw exceptions. This change supports coders that are easier to use and reason about, and are significantly faster. (4503732)

• Renamed substitution to replacement, which is more in line with the Unicode specification (and is also easier to spell). The replacement is returned by the replacement method and changed by the replaceWith method. (4503732)

• Generalized the handling of replacements so that separate actions can be specified for malformed-input vs. unmappable-character errors. The action to be taken when an error is encountered is specified by an instance of the CodingErrorAction class, which is a simple typesafe enumeration. The actions are specified via the onMalformedInput and onUnmappableCharacter methods; their current values can be retrieved via the malformedInputAction and unmappableCharacterAction methods. (4503732)

• Defined charset methods in the coder classes so that the charset that created a coder can be retrieved from the coder itself. (4503732)

• Added protected methods to better support subclasses: implReset, implFlush, implReplaceWith, implOnMalformedInput, and implOnUnmappableCharacter. These methods are invoked by the corresponding public methods after the public methods validate coder state and any arguments. Their default implementations do nothing. The implReset and implFlush methods were also required in order to implement coder state checking, i.e. the throwing of illegal-argument exceptions when a coder is used in a manner contrary to the specified coding-operation sequence. (4503732)

• Cleaned up the API for auto-detecting charsets in CharsetDecoder by adding the isAutoDetecting and isCharsetDetected methods and making detectedCharset an optional operation. (4503732)

• Defined the isLegalReplacement method in CharsetEncoder so that a replacement can be tested for validity without causing an exception to be thrown. (4503732)

• Revised UnmappableCharacterException to report the number of input units that denote the unmappable character. (4503732)

• Added the convenience methods Charset.decode(ByteBuffer), Charset.encode(CharBuffer), and Charset.encode(String).

• Changed the default error actions of CharsetDecoder and CharsetEncoder to be to report both malformed-input and unmappable-character errors. This does not affect coding operations performed by pre-Merlin APIs, which continue to replace erroneous input rather than report it.

• Added constructors to InputStreamReader and OutputStreamWriter that take existing CharsetDecoder and CharsetEncoder objects, respectively. (4426480)

Regular expressions

• Removed the conditional construct (?(cond)yes|no), since this is only an experimental feature in Perl. (4482696)

• Removed < and > as metacharacters since they conflicted too easily with commonly-used tokens in HTML and XML. (4482696)

• Removed vertical tab and form feed as line terminators. (4482696)

• Added a new Pattern.UNIX_LINES mode, and the corresponding pattern flag (?d), that recognizes only newlines ('\n') as line terminators. (4482696)

• Interpret dangling brackets ( ] ) and braces ( } ) as literals, as Perl does. (4482696)

• Changed the way back references are parsed to more closely match the way Perl interprets them. (4482696)

• Removed the cut operator (!), since this is not supported by Perl. (4482696)

• Added the Pattern.COMMENTS mode, and the corresponding Perl-style pattern flag (?x), in which whitespace and comments can be embedded in a regular expression. (4482696)

• Revised the character-class syntax to support the union and intersection of character classes via union ([X[Y]]), intersection ([X&&Y]), and complement ([^X]). (4482696)

• Changed the ^ metacharacter so that it will not match after the final line terminator, since it does not do so in Perl. (4482696)

• Revised all group constructs starting with (? so that they are treated as pure groups and do not capture text. (4482696)

• Added the \G boundary matcher. (4470527)

• Added Matcher.find(int startAt). (4474290)

• Changed the replacement-string syntax in the Matcher class from $(n) to $n, and defined the escaping of $ to be more like Perl's. (4479128)

• Revised the split methods in Pattern and String to match Perl's behavior. (4497806)

• Revised the block/category syntax to match Perl's \p{Foo} and \P{Foo} syntax. (4495089)

• Revised the names of the POSIX character classes to match the capitalized names used by Perl. (4495089)

• Added String.matches(regex), a more convenient way to invoke Pattern.matches(regex, input).

• Added String.replaceAll(regex, repl), a more convenient way to invoke Matcher.replaceAll(repl).

• Added replaceFirst(regex, repl) methods to both String and Matcher.

• Added description, pattern, and index properties to PatternSyntaxException.

Other

• Improved invocation chaining: Revised the methods DatagramChannel.connect, DatagramChannel.disconnect, FileChannel.position(long), FileChannel.truncate(long), SelectableChannel.configureBlocking, SelectionKey.interestOps(int), Selector.wakeup, Matcher.appendReplacement, Matcher.reset(), and Matcher.reset(java.lang.CharSequence) to return the object upon which they are invoked. Revised Matcher.appendTail to return the string-buffer object passed to it.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

Java Software