Merge IO v2 branch to bleeding edge

sdk/lib/io/file.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * FileMode describes the modes in which a file can be opened.
  */
 class FileMode {
   static const READ = const FileMode._internal(0);
   static const WRITE = const FileMode._internal(1);
   static const APPEND = const FileMode._internal(2);
   const FileMode._internal(int this._mode);
   final int _mode;
 }
 
 
 /**
  * [File] objects are references to files.
  *
- * To operate on the underlying file data you need to either get
- * streams using [openInputStream] and [openOutputStream] or open the
- * file for random access operations using [open].
+ * To operate on the underlying file data there are two options:
+ *
+ *  * use streaming by getting a [Stream] for the contents of the file
+ *    with [openRead] and by getting a [IOSink] for
+ *    writing contents to the file using [openWrite], or
+ *  * open the file for random access operations using [open].
  */
-abstract class File {
+abstract class File extends FileSystemEntity {
   /**
    * Create a File object.
    */
   factory File(String name) => new _File(name);
 
   /**
    * Create a File object from a Path object.
    */
   factory File.fromPath(Path path) => new _File.fromPath(path);
 
@@ skipping 107 matching lines @@
    * Returns a [:Future<String>:] that completes with the path.
    */
   Future<String> fullPath();
 
   /**
    * Synchronously get the canonical full path corresponding to the file name.
    */
   String fullPathSync();
 
   /**
-   * Create a new independent input stream for the file. The file
-   * input stream must be closed when no longer used to free up system
-   * resources.
+   * Create a new independent [Stream] for the contents of this
+   * file.
+   *
+   * In order to make sure that system resources are freed, the stream
+   * must be read to completion or the subscription on the stream must
+   * be cancelled.
    */
-  InputStream openInputStream();
+  Stream<List<int>> openRead();
+
 
   /**
-   * Creates a new independent output stream for the file. The file
-   * output stream must be closed when no longer used to free up
+   * Creates a new independent [IOSink] for the file. The
+   * stream consumer must be closed when no longer used to free up
    * system resources.
    *
-   * An output stream can be opened in two modes:
+   * A IOSink can be opened for a file in two modes:
    *
-   * FileMode.WRITE: create the stream and truncate the underlying
-   * file to length zero.
-   *
-   * FileMode.APPEND: create the stream and set the position to the end of
-   * the underlying file.
+   * * FileMode.WRITE: truncates the underlying file to length zero.
+   * * FileMode.APPEND: sets the position to the end of the underlying file.
    */
-  OutputStream openOutputStream([FileMode mode = FileMode.WRITE]);
+  IOSink<File> openWrite([FileMode mode = FileMode.WRITE]);
 
   /**
    * Read the entire file contents as a list of bytes. Returns a
    * [:Future<List<int>>:] that completes with the list of bytes that
    * is the contents of the file.
    */
   Future<List<int>> readAsBytes();
 
   /**
    * Synchronously read the entire file contents as a list of bytes.
@@ skipping 267 matching lines @@
         sb.add(" ($osError)");
       }
     } else if (osError != null) {
       sb.add(": osError");
     }
     return sb.toString();
   }
   final String message;
   final OSError osError;
 }