Back to index...

	/*
	* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package java.io;

	import java.util.ArrayList;
	import java.util.List;
	import java.util.Objects;

	import jdk.internal.access.JavaIOFileDescriptorAccess;
	import jdk.internal.access.SharedSecrets;
	import jdk.internal.ref.PhantomCleanable;

	/**
	* Instances of the file descriptor class serve as an opaque handle
	* to the underlying machine-specific structure representing an open
	* file, an open socket, or another source or sink of bytes.
	* The main practical use for a file descriptor is to create a
	* {@link FileInputStream} or {@link FileOutputStream} to contain it.
	* <p>
	* Applications should not create their own file descriptors.
	*
	* @author Pavani Diwanji
	* @since 1.0
	*/
	public final class FileDescriptor {

	private int fd;

	private long handle;

	private Closeable parent;
	private List<Closeable> otherParents;
	private boolean closed;

	/**
	* true, if file is opened for appending.
	*/
	private boolean append;

	static {
	initIDs();
	}

	// Set up JavaIOFileDescriptorAccess in SharedSecrets
	static {
	SharedSecrets.setJavaIOFileDescriptorAccess(
	new JavaIOFileDescriptorAccess() {
	public void set(FileDescriptor fdo, int fd) {
	fdo.set(fd);
	}

	public int get(FileDescriptor fdo) {
	return fdo.fd;
	}

	public void setAppend(FileDescriptor fdo, boolean append) {
	fdo.append = append;
	}

	public boolean getAppend(FileDescriptor fdo) {
	return fdo.append;
	}

	public void close(FileDescriptor fdo) throws IOException {
	fdo.close();
	}

	/* Register for a normal FileCleanable fd/handle cleanup. */
	public void registerCleanup(FileDescriptor fdo) {
	FileCleanable.register(fdo);
	}

	/* Register a custom PhantomCleanup. */
	public void registerCleanup(FileDescriptor fdo,
	PhantomCleanable<FileDescriptor> cleanup) {
	fdo.registerCleanup(cleanup);
	}

	public void unregisterCleanup(FileDescriptor fdo) {
	fdo.unregisterCleanup();
	}

	public void setHandle(FileDescriptor fdo, long handle) {
	fdo.setHandle(handle);
	}

	public long getHandle(FileDescriptor fdo) {
	return fdo.handle;
	}
	}
	);
	}

	/**
	* Cleanup in case FileDescriptor is not explicitly closed.
	*/
	private PhantomCleanable<FileDescriptor> cleanup;

	/**
	* Constructs an (invalid) FileDescriptor object.
	* The fd or handle is set later.
	*/
	public FileDescriptor() {
	fd = -1;
	handle = -1;
	}

	/**
	* Used for standard input, output, and error only.
	* For Windows the corresponding handle is initialized.
	* For Unix the append mode is cached.
	* @param fd the raw fd number (0, 1, 2)
	*/
	private FileDescriptor(int fd) {
	this.fd = fd;
	this.handle = getHandle(fd);
	this.append = getAppend(fd);
	}

	/**
	* A handle to the standard input stream. Usually, this file
	* descriptor is not used directly, but rather via the input stream
	* known as {@code System.in}.
	*
	* @see java.lang.System#in
	*/
	public static final FileDescriptor in = new FileDescriptor(0);

	/**
	* A handle to the standard output stream. Usually, this file
	* descriptor is not used directly, but rather via the output stream
	* known as {@code System.out}.
	* @see java.lang.System#out
	*/
	public static final FileDescriptor out = new FileDescriptor(1);

	/**
	* A handle to the standard error stream. Usually, this file
	* descriptor is not used directly, but rather via the output stream
	* known as {@code System.err}.
	*
	* @see java.lang.System#err
	*/
	public static final FileDescriptor err = new FileDescriptor(2);

	/**
	* Tests if this file descriptor object is valid.
	*
	* @return {@code true} if the file descriptor object represents a
	* valid, open file, socket, or other active I/O connection;
	* {@code false} otherwise.
	*/
	public boolean valid() {
	return (handle != -1) \|\| (fd != -1);
	}

	/**
	* Force all system buffers to synchronize with the underlying
	* device. This method returns after all modified data and
	* attributes of this FileDescriptor have been written to the
	* relevant device(s). In particular, if this FileDescriptor
	* refers to a physical storage medium, such as a file in a file
	* system, sync will not return until all in-memory modified copies
	* of buffers associated with this FileDescriptor have been
	* written to the physical medium.
	*
	* sync is meant to be used by code that requires physical
	* storage (such as a file) to be in a known state For
	* example, a class that provided a simple transaction facility
	* might use sync to ensure that all changes to a file caused
	* by a given transaction were recorded on a storage medium.
	*
	* sync only affects buffers downstream of this FileDescriptor. If
	* any in-memory buffering is being done by the application (for
	* example, by a BufferedOutputStream object), those buffers must
	* be flushed into the FileDescriptor (for example, by invoking
	* OutputStream.flush) before that data will be affected by sync.
	*
	* @throws SyncFailedException
	* Thrown when the buffers cannot be flushed,
	* or because the system cannot guarantee that all the
	* buffers have been synchronized with physical media.
	* @since 1.1
	*/
	public native void sync() throws SyncFailedException;

	/* This routine initializes JNI field offsets for the class */
	private static native void initIDs();

	/*
	* On Windows return the handle for the standard streams.
	*/
	private static native long getHandle(int d);

	/**
	* Returns true, if the file was opened for appending.
	*/
	private static native boolean getAppend(int fd);

	/**
	* Set the fd.
	* Used on Unix and for sockets on Windows and Unix.
	* If setting to -1, clear the cleaner.
	* The {@link #registerCleanup} method should be called for new fds.
	* @param fd the raw fd or -1 to indicate closed
	*/
	@SuppressWarnings("unchecked")
	synchronized void set(int fd) {
	if (fd == -1 && cleanup != null) {
	cleanup.clear();
	cleanup = null;
	}
	this.fd = fd;
	}

	/**
	* Set the handle.
	* Used on Windows for regular files.
	* If setting to -1, clear the cleaner.
	* The {@link #registerCleanup} method should be called for new handles.
	* @param handle the handle or -1 to indicate closed
	*/
	@SuppressWarnings("unchecked")
	void setHandle(long handle) {
	if (handle == -1 && cleanup != null) {
	cleanup.clear();
	cleanup = null;
	}
	this.handle = handle;
	}

	/**
	* Register a cleanup for the current handle.
	* Used directly in java.io and indirectly via fdAccess.
	* The cleanup should be registered after the handle is set in the FileDescriptor.
	* @param cleanable a PhantomCleanable to register
	*/
	@SuppressWarnings("unchecked")
	synchronized void registerCleanup(PhantomCleanable<FileDescriptor> cleanable) {
	Objects.requireNonNull(cleanable, "cleanable");
	if (cleanup != null) {
	cleanup.clear();
	}
	cleanup = cleanable;
	}

	/**
	* Unregister a cleanup for the current raw fd or handle.
	* Used directly in java.io and indirectly via fdAccess.
	* Normally {@link #close()} should be used except in cases where
	* it is certain the caller will close the raw fd and the cleanup
	* must not close the raw fd. {@link #unregisterCleanup()} must be
	* called before the raw fd is closed to prevent a race that makes
	* it possible for the fd to be reallocated to another use and later
	* the cleanup might be invoked.
	*/
	synchronized void unregisterCleanup() {
	if (cleanup != null) {
	cleanup.clear();
	}
	cleanup = null;
	}

	/**
	* Close the raw file descriptor or handle, if it has not already been closed.
	* The native code sets the fd and handle to -1.
	* Clear the cleaner so the close does not happen twice.
	* Package private to allow it to be used in java.io.
	* @throws IOException if close fails
	*/
	@SuppressWarnings("unchecked")
	synchronized void close() throws IOException {
	unregisterCleanup();
	close0();
	}

	/*
	* Close the raw file descriptor or handle, if it has not already been closed
	* and set the fd and handle to -1.
	*/
	private native void close0() throws IOException;

	/*
	* Package private methods to track referents.
	* If multiple streams point to the same FileDescriptor, we cycle
	* through the list of all referents and call close()
	*/

	/**
	* Attach a Closeable to this FD for tracking.
	* parent reference is added to otherParents when
	* needed to make closeAll simpler.
	*/
	synchronized void attach(Closeable c) {
	if (parent == null) {
	// first caller gets to do this
	parent = c;
	} else if (otherParents == null) {
	otherParents = new ArrayList<>();
	otherParents.add(parent);
	otherParents.add(c);
	} else {
	otherParents.add(c);
	}
	}

	/**
	* Cycle through all Closeables sharing this FD and call
	* close() on each one.
	*
	* The caller closeable gets to call close0().
	*/
	@SuppressWarnings("try")
	synchronized void closeAll(Closeable releaser) throws IOException {
	if (!closed) {
	closed = true;
	IOException ioe = null;
	try (releaser) {
	if (otherParents != null) {
	for (Closeable referent : otherParents) {
	try {
	referent.close();
	} catch(IOException x) {
	if (ioe == null) {
	ioe = x;
	} else {
	ioe.addSuppressed(x);
	}
	}
	}
	}
	} catch(IOException ex) {
	/*
	* If releaser close() throws IOException
	* add other exceptions as suppressed.
	*/
	if (ioe != null)
	ex.addSuppressed(ioe);
	ioe = ex;
	} finally {
	if (ioe != null)
	throw ioe;
	}
	}
	}
	}

Back to index...