Skip to content

Commit f96bdf5

Browse files
[cross_file_platform_interface] Platform interface implementation of cross_file (flutter#12825)
Platform interface of `cross_file`. This depends on flutter/packages#12869 to land first. ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent cb4f49d commit f96bdf5

15 files changed

Lines changed: 1106 additions & 0 deletions
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Below is a list of people and organizations that have contributed
2+
# to the Flutter project. Names should be added to the list like so:
3+
#
4+
# Name/Organization <email address>
5+
6+
Google LLC
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## 1.0.0
2+
3+
* Initial release.
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Copyright 2013 The Flutter Authors
2+
3+
Redistribution and use in source and binary forms, with or without modification,
4+
are permitted provided that the following conditions are met:
5+
6+
* Redistributions of source code must retain the above copyright
7+
notice, this list of conditions and the following disclaimer.
8+
* Redistributions in binary form must reproduce the above
9+
copyright notice, this list of conditions and the following
10+
disclaimer in the documentation and/or other materials provided
11+
with the distribution.
12+
* Neither the name of Google Inc. nor the names of its
13+
contributors may be used to endorse or promote products derived
14+
from this software without specific prior written permission.
15+
16+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
20+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
23+
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# cross_file_platform_interface
2+
3+
A common platform interface for the [`cross_file`](https://pub.dev/packages/cross_file) plugin.
4+
5+
This interface allows platform implementations of the `cross_file` plugin, as well as the plugin
6+
itself, to ensure they are supporting the same interface.
7+
8+
# Usage
9+
10+
To implement a new platform implementation of `cross_file`, extend
11+
[`CrossFilePlatform`](lib/src/cross_file_platform.dart) with an implementation that performs the
12+
platform-specific behavior, and when you register your plugin, set the default
13+
`CrossFilePlatform` by calling `CrossFilePlatform.instance = CrossFileMyPlatform()`.
14+
15+
# Note on breaking changes
16+
17+
Strongly prefer non-breaking changes (such as adding a method to the interface)
18+
over breaking changes for this package.
19+
20+
See https://flutter.dev/go/platform-interface-breaking-changes for a discussion on why a less-clean
21+
interface is preferable to a breaking change.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
export 'src/cross_file_platform.dart';
6+
export 'src/file_system/platform_file_system_cross_directory.dart';
7+
export 'src/file_system/platform_file_system_cross_file.dart';
8+
export 'src/platform_cross_directory.dart';
9+
export 'src/platform_cross_entity.dart';
10+
export 'src/platform_cross_file.dart';
11+
export 'src/scoped_storage/platform_scoped_storage_cross_directory.dart';
12+
export 'src/scoped_storage/platform_scoped_storage_cross_file.dart';
Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'dart:convert';
6+
import 'dart:typed_data';
7+
8+
import 'file_system/platform_file_system_cross_directory.dart';
9+
import 'file_system/platform_file_system_cross_file.dart';
10+
import 'platform_cross_directory.dart';
11+
import 'platform_cross_entity.dart';
12+
import 'scoped_storage/platform_scoped_storage_cross_directory.dart';
13+
import 'scoped_storage/platform_scoped_storage_cross_file.dart';
14+
15+
/// Interface for a platform implementation of `cross_file`.
16+
abstract base class CrossFilePlatform {
17+
/// The instance of [CrossFilePlatform] to be used.
18+
///
19+
/// Platform implementations packages should set this with their own
20+
/// implementation of [CrossFilePlatform] when they register themselves.
21+
static CrossFilePlatform? instance;
22+
23+
/// Creates a new [PlatformFileSystemXFile].
24+
PlatformFileSystemXFile createPlatformFileSystemXFile(
25+
PlatformFileSystemXFileCreationParams params,
26+
) {
27+
return _DefaultFileSystemXFile(params);
28+
}
29+
30+
/// Creates a new [PlatformFileSystemXDirectory].
31+
PlatformFileSystemXDirectory createPlatformFileSystemXDirectory(
32+
PlatformFileSystemXDirectoryCreationParams params,
33+
) {
34+
return _DefaultFileSystemXDirectory(params);
35+
}
36+
37+
/// Creates a new [PlatformScopedStorageXFile].
38+
PlatformScopedStorageXFile createPlatformScopedStorageXFile(
39+
PlatformScopedStorageXFileCreationParams params,
40+
) {
41+
return _DefaultScopedStorageXFile(params);
42+
}
43+
44+
/// Creates a new [PlatformScopedStorageXDirectory].
45+
PlatformScopedStorageXDirectory createPlatformScopedStorageXDirectory(
46+
PlatformScopedStorageXDirectoryCreationParams params,
47+
) {
48+
return _DefaultScopedStorageXDirectory(params);
49+
}
50+
}
51+
52+
/// Implementation of [PlatformFileSystemXFile] that represents a resource that
53+
/// does not exist.
54+
final class _DefaultFileSystemXFile extends PlatformFileSystemXFile {
55+
_DefaultFileSystemXFile(super.params) : super.implementation();
56+
57+
@override
58+
Future<bool> exists() async => false;
59+
60+
@override
61+
Future<DateTime?> lastModified() async => null;
62+
63+
@override
64+
Future<int?> length() async => null;
65+
66+
@override
67+
Future<String?> name() async => null;
68+
69+
@override
70+
Stream<Uint8List> openRead([int? start, int? end]) async* {
71+
throw UnsupportedError('This instance does not represent any resource.');
72+
}
73+
74+
@override
75+
Future<Uint8List> readAsBytes() {
76+
throw UnsupportedError('This instance does not represent any resource.');
77+
}
78+
79+
@override
80+
Future<String> readAsString({Encoding encoding = utf8}) {
81+
throw UnsupportedError('This instance does not represent any resource.');
82+
}
83+
84+
@override
85+
Future<PlatformFileSystemXFile> writeAsBytes(PlatformWriteAsBytesParams params) {
86+
throw UnsupportedError('This instance does not represent any resource.');
87+
}
88+
}
89+
90+
/// Implementation of [PlatformFileSystemXDirectory] that represents a directory
91+
/// that does not exist.
92+
final class _DefaultFileSystemXDirectory extends PlatformFileSystemXDirectory {
93+
_DefaultFileSystemXDirectory(super.params) : super.implementation();
94+
95+
@override
96+
Future<bool> exists() async => false;
97+
98+
@override
99+
Stream<PlatformXEntity> list(PlatformListParams params) async* {
100+
throw UnsupportedError('This instance does not represent any directory.');
101+
}
102+
}
103+
104+
/// Implementation of [PlatformScopedStorageXFile] that represents a resource
105+
/// that does not exist.
106+
final class _DefaultScopedStorageXFile extends PlatformScopedStorageXFile {
107+
_DefaultScopedStorageXFile(super.params) : super.implementation();
108+
109+
@override
110+
Future<bool> canRead() async => false;
111+
112+
@override
113+
Future<bool> exists() async => false;
114+
115+
@override
116+
Future<DateTime?> lastModified() async => null;
117+
118+
@override
119+
Future<int?> length() async => null;
120+
121+
@override
122+
Future<String?> name() async => null;
123+
124+
@override
125+
Stream<Uint8List> openRead([int? start, int? end]) async* {
126+
throw UnsupportedError('This instance does not represent any resource.');
127+
}
128+
129+
@override
130+
Future<Uint8List> readAsBytes() {
131+
throw UnsupportedError('This instance does not represent any resource.');
132+
}
133+
134+
@override
135+
Future<String> readAsString({Encoding encoding = utf8}) {
136+
throw UnsupportedError('This instance does not represent any resource.');
137+
}
138+
139+
@override
140+
Future<void> dispose() async {}
141+
}
142+
143+
/// Implementation of [PlatformScopedStorageXDirectory] that represents a
144+
/// directory that does not exist.
145+
final class _DefaultScopedStorageXDirectory extends PlatformScopedStorageXDirectory {
146+
_DefaultScopedStorageXDirectory(super.params) : super.implementation();
147+
148+
@override
149+
Future<bool> exists() async => false;
150+
151+
@override
152+
Future<bool> canRead() async => false;
153+
154+
@override
155+
Stream<PlatformXEntity> list(PlatformListParams params) async* {
156+
throw UnsupportedError('This instance does not represent any directory.');
157+
}
158+
159+
@override
160+
Future<void> dispose() async {}
161+
}
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/foundation.dart';
6+
7+
import '../cross_file_platform.dart';
8+
import '../platform_cross_directory.dart';
9+
10+
/// Object specifying creation parameters for creating a [PlatformFileSystemXDirectory].
11+
///
12+
/// Platform-specific implementations can add additional fields by extending
13+
/// this class.
14+
///
15+
/// This example demonstrates how to extend the [PlatformFileSystemXDirectoryCreationParams] to
16+
/// provide additional platform-specific parameters.
17+
///
18+
/// When extending [PlatformFileSystemXDirectoryCreationParams] additional parameters
19+
/// should always accept `null` or have a default value to prevent breaking
20+
/// changes.
21+
///
22+
/// ```dart
23+
/// base class AndroidFileSystemXDirectoryCreationParams
24+
/// extends PlatformFileSystemXDirectoryCreationParams {
25+
/// AndroidFileSystemXDirectoryCreationParams({required super.uri, this.platformValue});
26+
///
27+
/// factory AndroidFileSystemXDirectoryCreationParams.fromCreationParams(
28+
/// PlatformFileSystemXDirectoryCreationParams params, {
29+
/// Object? platformValue,
30+
/// }) {
31+
/// return AndroidFileSystemXDirectoryCreationParams(
32+
/// uri: params.uri,
33+
/// platformValue: platformValue,
34+
/// );
35+
/// }
36+
///
37+
/// final Object? platformValue;
38+
/// }
39+
/// ```
40+
@immutable
41+
base class PlatformFileSystemXDirectoryCreationParams extends PlatformXDirectoryCreationParams {
42+
/// Constructs a [PlatformFileSystemXDirectoryCreationParams].
43+
PlatformFileSystemXDirectoryCreationParams(this.path)
44+
: super(uri: Uri.directory(path).toString());
45+
46+
/// The path of the directory.
47+
final String path;
48+
}
49+
50+
/// Base mixin used to provide platform-specific features for implementations of
51+
/// [PlatformFileSystemXDirectory].
52+
///
53+
/// When providing platform specific features, platform implementations are
54+
/// expected to declare a mixin that implements this mixin and return an
55+
/// instance with [PlatformFileSystemXDirectory.extension].
56+
///
57+
/// ```dart
58+
/// base class AndroidFileSystemXDirectory extends PlatformFileSystemXDirectory with AndroidFileSystemXDirectoryExtension {
59+
/// // ...
60+
/// @override
61+
/// PlatformFileSystemXDirectoryExtension? get extension => this;
62+
///
63+
/// Future<void> platformMethod() {
64+
/// // ...
65+
/// }
66+
/// }
67+
///
68+
/// mixin AndroidFileSystemXDirectoryExtension implements PlatformFileSystemXDirectoryExtension {
69+
/// Future<void> platformMethod();
70+
/// }
71+
/// ```
72+
mixin PlatformFileSystemXDirectoryExtension implements PlatformXDirectoryExtension {}
73+
74+
/// Interface for a reference to a directory (or folder) on the file system.
75+
abstract base class PlatformFileSystemXDirectory extends PlatformXDirectory {
76+
/// Creates a new [PlatformFileSystemXDirectory]
77+
factory PlatformFileSystemXDirectory(PlatformFileSystemXDirectoryCreationParams params) {
78+
assert(
79+
CrossFilePlatform.instance != null,
80+
'A platform implementation for `cross_file` has not been set. Please '
81+
'ensure that an implementation of `CrossFilePlatform` has been set to '
82+
'`CrossFilePlatform.instance` before use. For unit testing, '
83+
'`CrossFilePlatform.instance` can be set with your own test implementation.',
84+
);
85+
return CrossFilePlatform.instance!.createPlatformFileSystemXDirectory(params);
86+
}
87+
88+
/// Used by the platform implementation to create a new
89+
/// [PlatformFileSystemXDirectory].
90+
///
91+
/// Should only be used by platform implementations because they can't extend
92+
/// a class that only contains a factory constructor.
93+
@protected
94+
PlatformFileSystemXDirectory.implementation(
95+
PlatformFileSystemXDirectoryCreationParams super.params,
96+
);
97+
98+
@override
99+
PlatformFileSystemXDirectoryCreationParams get params =>
100+
super.params as PlatformFileSystemXDirectoryCreationParams;
101+
102+
/// Extension for providing platform-specific features.
103+
@override
104+
PlatformFileSystemXDirectoryExtension? get extension => null;
105+
}

0 commit comments

Comments
 (0)