| # 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