New I/O APIs for the Java Platform

Print-friendly Version

New I/O APIs for the Java Platform

JSR-51 Change Log

2002/1/9

PROPOSED CHANGES

Please send comments on these proposed changes to jsr-51-comments@jcp.org.

1-7: Errata for the Proposed Final Draft

A number of small but significant errors were discovered in the JSR-51 specification after the Proposed Final Draft was submitted. In order to prevent these errors from becoming a permanent part of the specification we propose to repair them before the Final Release. The repaired API will be implemented by the initial release of the Java 2 Platform, Standard Edition (J2SE), version 1.4. We apologize for these errors, but we are fortunate to have found them in time to fix them.

1: Correct return types in the FileChannel class

In the Proposed Final Draft we revised the transferTo and transferFrom methods of the FileChannel class to take long rather than int count arguments so that they could be used to transfer large (greater than 2³¹-1 bytes) files. Unfortunately we neglected to revise the return types of these methods from int to long, so as they stand these methods would be unable to transfer more than 2³¹-1 bytes even though their parameter types appear to allow that.

To repair these errors we propose to change the return types of these methods from int to long. Their new signatures will be (changes are in green):

public abstract long transferTo(long position, long count, WritableByteChannel target) throws IOException; public abstract long transferFrom(ReadableByteChannel src, long position, long count) throws IOException;

2: Correct return types in the scatter/gather interfaces

The ScatteringByteChannel interface defines two read methods, each of which returns an int value counting the number of bytes read. The GatheringByteChannel interface defines a similar pair of write methods, each of which return an int value counting the number of bytes written. All of these methods take an array of byte buffers as their first argument. A byte buffer can hold up to 2³¹-1 bytes, and these methods can be passed up to 2³¹-1 buffers, so these methods can be invoked in such a way as to request a transfer of up to 2⁶²-2³²+1 bytes. This value does not fit into a 32-bit int.

To repair these errors we propose to change the return types of the methods declared in the ScatteringByteChannel and GatheringByteChannel interfaces from int to long. Their new signatures will be (changes are in green):

public interface ScatteringByteChannel extends ReadableByteChannel { public long read(ByteBuffer[] dsts, int offset, int length) throws IOException; public long read(ByteBuffer[] dsts) throws IOException; } public interface GatheringByteChannel extends WritableByteChannel { public long write(ByteBuffer[] srcs, int offset, int length) throws IOException; public long write(ByteBuffer[] srcs) throws IOException; }

The ScatteringByteChannel and GatheringByteChannel interfaces are implemented by the DatagramChannel, FileChannel, and SocketChannel classes, so corresponding changes will also be made to the scatter/gather methods defined in those classes.

3: Add a security check to the CharsetProvider constructor

The current specification allows an untrusted applet, application, or installed extension to declare a charset provider. This represents a security risk since charsets are used throughout the system in potentially security-sensitive operations such as encoding and decoding file names, URLs, and I/O streams.

To eliminate this risk we propose to define a new runtime security permission, charsetProvider, and to revise the specification of the sole CharsetProvider constructor to read as follows (changes are in green):

protected CharsetProvider()

Initializes a new charset provider.

Throws:

SecurityException - If a security manager has been installed and it denies RuntimePermission("charsetProvider")

4: Replace the insecure CharsetProvider.putCharsets method

The abstract method CharsetProvider.putCharsets(Map) is implemented by charset providers. It is invoked by the implementation of the Charset.availableCharsets() method, passing the system-wide map of available charsets. This represents a security risk since the map is mutable, hence a poorly-written or malicious provider could corrupt it.

To eliminate this risk we propose to replace the putCharsets method with the new method:

public abstract Iterator charsets()

Creates an iterator that iterates over the charsets supported by this provider. This method is used in the implementation of the Charset.availableCharsets method.

Returns:

The new iterator

5: Add a security check to the SelectorProvider constructor

The current specification allows an untrusted application or installed extension to declare the system's default selector provider. This represents a security risk since the default selector provider is used by other components of the system to open network connections.

To eliminate this risk we propose to revise the specification of the sole SelectorProvider constructor to read as follows (changes are in green):

protected SelectorProvider()

Initializes a new instance of this class.

Throws:

SecurityException - If a security manager has been installed and it denies RuntimePermission("selectorProvider")

6: Remove the SelectorProvider.setProvider method

There are currently three ways for trusted code to declare its own selector provider as the system-wide default: Invoke the SelectorProvider.setProvider(SelectorProvider) method, set a system property on the command line, or make a provider available as a service. (The specification of the provider method describes the lookup algorithm in detail.)

The setProvider method is specified to work so long as a default provider has not yet been determined. The default provider is determined lazily, at the time of the first use of any NIO selector- or socket-related class. It is highly likely that, as the NIO APIs become more widely used within the platform, we will eventually reach a point at which the default selector provider will have to be determined before application code can invoke the setProvider method in order to install its own provider. If and when that happens, this method will stop working.

To avoid this problem we propose to remove the setProvider method. The remaining two ways of declaring the default selector provider are adequate, and it is better to remove this method now than to have to deprecate it in a future release.

7: Declare public static fields to be final in CodingErrorAction

The CodingErrorAction class is a typesafe enumeration that declares three constant values in the public static fields IGNORE, REPLACE, and REPORT. These fields should be declared final in order to prevent them from mistakenly being modified.

To repair this error we propose to add the final keyword to the declarations of these three fields. Their new signatures will be (changes are in green):

    public static final CodingErrorAction IGNORE;
    public static final CodingErrorAction REPLACE;
    public static final CodingErrorAction REPORT;

ACCEPTED CHANGES

No changes proposed to the JSR-51 specification have yet been accepted.

DEFERRED CHANGES

No changes proposed to the JSR-51 specification have yet been deferred.