$darkmode
Qore FileLocationHandler Module Reference 2.3
FileLocationHandler.qc.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* FileLocationHandler Copyright 2021 - 2023 Qore Technologies, s.r.o.
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
28 public struct FileHandlerOptionInfo {
30  string type;
31 
33  bool required = False;
34 
36  string desc;
37 
40 };
41 
43 public struct FileHandlerInfo {
45  string scheme;
47  *hash<string, hash<FileHandlerOptionInfo>> read_options;
49  *hash<string, hash<FileHandlerOptionInfo>> write_options;
50 };
51 
54 
55 public:
57 
63  string getTextFile(string scheme, string location, *hash<auto> opts);
64 
65 
67 
73  binary getBinaryFile(string scheme, string location, *hash<auto> opts);
74 
75 
77 
83  Qore::AbstractPollOperation getIoPollerForLocation(string scheme, string location, *hash<auto> opts);
84 
85 
87 
95  Qore::StreamReader getStreamReader(string scheme, string location, *hash<auto> opts);
96 
97 
99 
107  Qore::InputStream getBinaryStream(string scheme, string location, *hash<auto> opts);
108 
109 
111 
116  writeFile(string scheme, string location, data contents, *hash<auto> opts);
117 
118 
120 
132  OutputStreamWrapper getOutputStream(string scheme, string location, *hash<auto> opts);
133 
134 
136 
138  hash<string, hash<FileHandlerOptionInfo>> getReadOptions();
139 
140 
142 
144  hash<string, hash<FileHandlerOptionInfo>> getWriteOptions();
145 
146 
148 protected:
149  static string forceEncoding(string str, *string encoding);
150 public:
151 
152 
154 
160 protected:
161  abstract string getTextFileImpl(string scheme, string location, *hash<auto> opts);
162 public:
163 
165 
171 protected:
172  abstract binary getBinaryFileImpl(string scheme, string location, *hash<auto> opts);
173 public:
174 
176 
182 protected:
183  abstract Qore::AbstractPollOperation getIoPollerForLocationImpl(string scheme, string location, *hash<auto> opts);
184 public:
185 
187 
193 protected:
194  abstract Qore::StreamReader getStreamReaderImpl(string scheme, string location, *hash<auto> opts);
195 public:
196 
198 
204 protected:
205  abstract Qore::InputStream getBinaryStreamImpl(string scheme, string location, *hash<auto> opts);
206 public:
207 
209 
214 protected:
215  abstract writeFileImpl(string scheme, string location, data contents, *hash<auto> opts);
216 public:
217 
219 
231 protected:
232  abstract OutputStreamWrapper getOutputStreamImpl(string scheme, string location, *hash<auto> opts);
233 public:
234 
236 
238 protected:
239  abstract hash<string, hash<FileHandlerOptionInfo>> getReadOptionsImpl();
240 public:
241 
243 
245 protected:
246  abstract hash<string, hash<FileHandlerOptionInfo>> getWriteOptionsImpl();
247 public:
248 };
249 
252 
253 public:
254 protected:
256 
258  static hash<string, AbstractFileLocationHandler> cache;
259 
261  static Mutex handler_lock();
262 
264  static bool dynamic_init;
265 
266 public:
267 
269  static init();
270 
272 
278  static registerHandler(string scheme, AbstractFileLocationHandler handler);
279 
281 
288  static bool tryRegisterHandler(string scheme, AbstractFileLocationHandler handler);
289 
291 
293  static list<string> getSupportedSchemes();
294 
296 
300  static bool isSchemeSupported(string scheme);
301 
303 
309  static string getTextFileFromLocation(string location);
310 
312 
318  static binary getBinaryFileFromLocation(string location);
319 
321 
326  static data getFileFromLocation(bool text, string location);
327 
329 
334 
336 
341 
343 
348 
350 
353  static writeFileToLocation(string location, data contents);
354 
356 
366 
368 
372  static list<string> getHandlerNames();
373 
375 
382  static hash<string, hash<FileHandlerInfo>> getHandlers(*bool write);
383 
385 
391  static hash<FileHandlerInfo> getHandlerInfo(string scheme);
392 
394 
399 protected:
400  static hash<InternallLocationInfo> getInfo(string location, bool read);
401 public:
402 
403 
405 protected:
406  static *hash<auto> getOptions(reference<string> location);
407 public:
408 
409 
411 protected:
413 public:
414 
415 };
416 };
417 
418 namespace Priv {
419 hashdecl InternallLocationInfo {
420  string scheme;
421  string location;
422  *hash<auto> opts;
423  AbstractFileLocationHandler handler;
424 }
425 };
The abstract file location handler class.
Definition: FileLocationHandler.qc.dox.h:53
abstract string getTextFileImpl(string scheme, string location, *hash< auto > opts)
Retrieves a text file from the given location.
abstract binary getBinaryFileImpl(string scheme, string location, *hash< auto > opts)
Retrieves a binary file from the given location.
Qore::StreamReader getStreamReader(string scheme, string location, *hash< auto > opts)
Returns a string stream for the file's data at the given location.
abstract Qore::AbstractPollOperation getIoPollerForLocationImpl(string scheme, string location, *hash< auto > opts)
Retrieves an I/O poller to retrieve a binary file from the given location.
binary getBinaryFile(string scheme, string location, *hash< auto > opts)
Retrieves a binary file from the given location.
Qore::AbstractPollOperation getIoPollerForLocation(string scheme, string location, *hash< auto > opts)
Retrieves an I/O poller to retrieve a binary file from the given location.
string getTextFile(string scheme, string location, *hash< auto > opts)
Retrieves a text file from the given location.
hash< string, hash< FileHandlerOptionInfo > > getWriteOptions()
Gets supported write options.
abstract hash< string, hash< FileHandlerOptionInfo > > getReadOptionsImpl()
Gets supported read options.
abstract Qore::StreamReader getStreamReaderImpl(string scheme, string location, *hash< auto > opts)
Returns a string stream for the file's data at the given location.
writeFile(string scheme, string location, data contents, *hash< auto > opts)
Writes data to a file at the given location.
abstract hash< string, hash< FileHandlerOptionInfo > > getWriteOptionsImpl()
Gets supported write options.
OutputStreamWrapper getOutputStream(string scheme, string location, *hash< auto > opts)
Returns an output stream for writing data to the given location.
Qore::InputStream getBinaryStream(string scheme, string location, *hash< auto > opts)
Retrieves a binary file from the given location.
abstract OutputStreamWrapper getOutputStreamImpl(string scheme, string location, *hash< auto > opts)
Returns an output stream for writing data to the given location.
abstract Qore::InputStream getBinaryStreamImpl(string scheme, string location, *hash< auto > opts)
Retrieves a binary file from the given location.
static string forceEncoding(string str, *string encoding)
Returns a string tagged with the given encoding, if any.
abstract writeFileImpl(string scheme, string location, data contents, *hash< auto > opts)
Writes data to a file at the given location.
hash< string, hash< FileHandlerOptionInfo > > getReadOptions()
Gets supported read options.
static data getFileFromLocation(bool text, string location)
Returns the file data from the given location.
static Qore::StreamReader getStreamReaderFromLocation(string location)
Returns a string stream for the file's data at the given location.
static list< string > getHandlerNames()
Returns a list of all handler names.
static Qore::InputStream getBinaryStreamFromLocation(string location)
Returns an input stream for file data at the given location.
static bool isSchemeSupported(string scheme)
Returns True if the scheme is supported.
static hash< InternallLocationInfo > getInfo(string location, bool read)
Returns info about the requested location.
static hash< string, hash< FileHandlerInfo > > getHandlers(*bool write)
Returns info about all cached handlers.
static Qore::AbstractPollOperation getIoPollerForLocation(string location)
Returns a non-blocking I/O poller object to retrieve a binary file from the given location.
static registerHandler(string scheme, AbstractFileLocationHandler handler)
Register a new location handler.
static hash< string, AbstractFileLocationHandler > cache
The location handler cache; scheme -> handler;.
Definition: FileLocationHandler.qc.dox.h:258
static bool dynamic_init
Flag for dynamic initialization.
Definition: FileLocationHandler.qc.dox.h:264
static bool tryRegisterHandler(string scheme, AbstractFileLocationHandler handler)
Tries to register a new location handler; if the scheme is already registered, the method returns Fal...
static OutputStreamWrapper getOutputStreamForLocation(string location)
Returns an output stream for writing data to the given location.
static list< string > getSupportedSchemes()
Retuns a list of supported schemes.
static init()
Initializes default handlers.
static hash< FileHandlerInfo > getHandlerInfo(string scheme)
Returns info about the location handler for he given scheme.
static checkDynamicInit()
Checks for dynamic initialization.
static *hash< auto > getOptions(reference< string > location)
Returns a hash of options from the location string.
static binary getBinaryFileFromLocation(string location)
Returns binary data for the given file location.
static Mutex handler_lock()
The location handler lock to ensure atomic operations.
static writeFileToLocation(string location, data contents)
Writes data to a file at the given location.
static string getTextFileFromLocation(string location)
Returns string data for the given file location.
The abstract file location handler class.
Definition: OutputStramWrapper.qc.dox.h:28
const False
binary binary()
Contains all public definitions in the FileLocationHandler module.
Definition: FileLocationHandler.qc.dox.h:26
File handler info.
Definition: FileLocationHandler.qc.dox.h:43
*hash< string, hash< FileHandlerOptionInfo > > read_options
Read options, if any.
Definition: FileLocationHandler.qc.dox.h:47
*hash< string, hash< FileHandlerOptionInfo > > write_options
Write options, if any.
Definition: FileLocationHandler.qc.dox.h:49
string scheme
The schema handled.
Definition: FileLocationHandler.qc.dox.h:45
File handler option info.
Definition: FileLocationHandler.qc.dox.h:28
string type
The option value type: "string", "bool", or "int".
Definition: FileLocationHandler.qc.dox.h:30
auto default_value
Default value, if any.
Definition: FileLocationHandler.qc.dox.h:39
string desc
The option description.
Definition: FileLocationHandler.qc.dox.h:36
bool required
Required flag.
Definition: FileLocationHandler.qc.dox.h:33