001: /*
002: * Copyright 2003-2007 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.io;
027:
028: import java.util.concurrent.atomic.AtomicInteger;
029:
030: /**
031: * Instances of the file descriptor class serve as an opaque handle
032: * to the underlying machine-specific structure representing an open
033: * file, an open socket, or another source or sink of bytes. The
034: * main practical use for a file descriptor is to create a
035: * <code>FileInputStream</code> or <code>FileOutputStream</code> to
036: * contain it.
037: * <p>
038: * Applications should not create their own file descriptors.
039: *
040: * @author Pavani Diwanji
041: * @version 1.12, 06/14/07
042: * @see java.io.FileInputStream
043: * @see java.io.FileOutputStream
044: * @since JDK1.0
045: */
046: public final class FileDescriptor {
047:
048: private int fd;
049:
050: private long handle;
051:
052: /**
053: * A use counter for tracking the FIS/FOS/RAF instances that
054: * use this FileDescriptor. The FIS/FOS.finalize() will not release
055: * the FileDescriptor if it is still under use by any stream.
056: */
057: private AtomicInteger useCount;
058:
059: /**
060: * Constructs an (invalid) FileDescriptor
061: * object.
062: */
063: public/**/FileDescriptor() {
064: fd = -1;
065: handle = -1;
066: useCount = new AtomicInteger();
067: }
068:
069: static {
070: initIDs();
071: }
072:
073: // Set up JavaIOFileDescriptorAccess in SharedSecrets
074: static {
075: sun.misc.SharedSecrets
076: .setJavaIOFileDescriptorAccess(new sun.misc.JavaIOFileDescriptorAccess() {
077: public void set(FileDescriptor obj, int fd) {
078: obj.fd = fd;
079: }
080:
081: public int get(FileDescriptor obj) {
082: return obj.fd;
083: }
084: });
085: }
086:
087: /**
088: * A handle to the standard input stream. Usually, this file
089: * descriptor is not used directly, but rather via the input stream
090: * known as <code>System.in</code>.
091: *
092: * @see java.lang.System#in
093: */
094: public static final FileDescriptor in = standardStream(0);
095:
096: /**
097: * A handle to the standard output stream. Usually, this file
098: * descriptor is not used directly, but rather via the output stream
099: * known as <code>System.out</code>.
100: * @see java.lang.System#out
101: */
102: public static final FileDescriptor out = standardStream(1);
103:
104: /**
105: * A handle to the standard error stream. Usually, this file
106: * descriptor is not used directly, but rather via the output stream
107: * known as <code>System.err</code>.
108: *
109: * @see java.lang.System#err
110: */
111: public static final FileDescriptor err = standardStream(2);
112:
113: /**
114: * Tests if this file descriptor object is valid.
115: *
116: * @return <code>true</code> if the file descriptor object represents a
117: * valid, open file, socket, or other active I/O connection;
118: * <code>false</code> otherwise.
119: */
120: public boolean valid() {
121: return ((handle != -1) || (fd != -1));
122: }
123:
124: /**
125: * Force all system buffers to synchronize with the underlying
126: * device. This method returns after all modified data and
127: * attributes of this FileDescriptor have been written to the
128: * relevant device(s). In particular, if this FileDescriptor
129: * refers to a physical storage medium, such as a file in a file
130: * system, sync will not return until all in-memory modified copies
131: * of buffers associated with this FileDesecriptor have been
132: * written to the physical medium.
133: *
134: * sync is meant to be used by code that requires physical
135: * storage (such as a file) to be in a known state For
136: * example, a class that provided a simple transaction facility
137: * might use sync to ensure that all changes to a file caused
138: * by a given transaction were recorded on a storage medium.
139: *
140: * sync only affects buffers downstream of this FileDescriptor. If
141: * any in-memory buffering is being done by the application (for
142: * example, by a BufferedOutputStream object), those buffers must
143: * be flushed into the FileDescriptor (for example, by invoking
144: * OutputStream.flush) before that data will be affected by sync.
145: *
146: * @exception SyncFailedException
147: * Thrown when the buffers cannot be flushed,
148: * or because the system cannot guarantee that all the
149: * buffers have been synchronized with physical media.
150: * @since JDK1.1
151: */
152: public native void sync() throws SyncFailedException;
153:
154: /* This routine initializes JNI field offsets for the class */
155: private static native void initIDs();
156:
157: private static native long set(int d);
158:
159: private static FileDescriptor standardStream(int fd) {
160: FileDescriptor desc = new FileDescriptor();
161: desc.handle = set(fd);
162: return desc;
163: }
164:
165: // package private methods used by FIS, FOS and RAF.
166:
167: int incrementAndGetUseCount() {
168: return useCount.incrementAndGet();
169: }
170:
171: int decrementAndGetUseCount() {
172: return useCount.decrementAndGet();
173: }
174: }
|