001: /*
002: * Copyright 1995-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.30, 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: /**
051: * A counter for tracking the FIS/FOS/RAF instances that
052: * use this FileDescriptor. The FIS/FOS.finalize() will not release
053: * the FileDescriptor if it is still under user by a stream.
054: */
055: private AtomicInteger useCount;
056:
057: /**
058: * Constructs an (invalid) FileDescriptor
059: * object.
060: */
061: public/**/FileDescriptor() {
062: fd = -1;
063: useCount = new AtomicInteger();
064: }
065:
066: private/* */FileDescriptor(int fd) {
067: this .fd = fd;
068: useCount = new AtomicInteger();
069: }
070:
071: /**
072: * A handle to the standard input stream. Usually, this file
073: * descriptor is not used directly, but rather via the input stream
074: * known as <code>System.in</code>.
075: *
076: * @see java.lang.System#in
077: */
078: public static final FileDescriptor in = new FileDescriptor(0);
079:
080: /**
081: * A handle to the standard output stream. Usually, this file
082: * descriptor is not used directly, but rather via the output stream
083: * known as <code>System.out</code>.
084: * @see java.lang.System#out
085: */
086: public static final FileDescriptor out = new FileDescriptor(1);
087:
088: /**
089: * A handle to the standard error stream. Usually, this file
090: * descriptor is not used directly, but rather via the output stream
091: * known as <code>System.err</code>.
092: *
093: * @see java.lang.System#err
094: */
095: public static final FileDescriptor err = new FileDescriptor(2);
096:
097: /**
098: * Tests if this file descriptor object is valid.
099: *
100: * @return <code>true</code> if the file descriptor object represents a
101: * valid, open file, socket, or other active I/O connection;
102: * <code>false</code> otherwise.
103: */
104: public boolean valid() {
105: return fd != -1;
106: }
107:
108: /**
109: * Force all system buffers to synchronize with the underlying
110: * device. This method returns after all modified data and
111: * attributes of this FileDescriptor have been written to the
112: * relevant device(s). In particular, if this FileDescriptor
113: * refers to a physical storage medium, such as a file in a file
114: * system, sync will not return until all in-memory modified copies
115: * of buffers associated with this FileDescriptor have been
116: * written to the physical medium.
117: *
118: * sync is meant to be used by code that requires physical
119: * storage (such as a file) to be in a known state For
120: * example, a class that provided a simple transaction facility
121: * might use sync to ensure that all changes to a file caused
122: * by a given transaction were recorded on a storage medium.
123: *
124: * sync only affects buffers downstream of this FileDescriptor. If
125: * any in-memory buffering is being done by the application (for
126: * example, by a BufferedOutputStream object), those buffers must
127: * be flushed into the FileDescriptor (for example, by invoking
128: * OutputStream.flush) before that data will be affected by sync.
129: *
130: * @exception SyncFailedException
131: * Thrown when the buffers cannot be flushed,
132: * or because the system cannot guarantee that all the
133: * buffers have been synchronized with physical media.
134: * @since JDK1.1
135: */
136: public native void sync() throws SyncFailedException;
137:
138: /* This routine initializes JNI field offsets for the class */
139: private static native void initIDs();
140:
141: static {
142: initIDs();
143: }
144:
145: // Set up JavaIOFileDescriptorAccess in SharedSecrets
146: static {
147: sun.misc.SharedSecrets
148: .setJavaIOFileDescriptorAccess(new sun.misc.JavaIOFileDescriptorAccess() {
149: public void set(FileDescriptor obj, int fd) {
150: obj.fd = fd;
151: }
152:
153: public int get(FileDescriptor obj) {
154: return obj.fd;
155: }
156: });
157: }
158:
159: // pacakge private methods used by FIS,FOS and RAF
160:
161: int incrementAndGetUseCount() {
162: return useCount.incrementAndGet();
163: }
164:
165: int decrementAndGetUseCount() {
166: return useCount.decrementAndGet();
167: }
168: }
|