1/**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19#ifndef ORC_FILE_HH
20#define ORC_FILE_HH
21
22#include <string>
23
24#include "orc/orc-config.hh"
25#include "orc/Reader.hh"
26#include "orc/Writer.hh"
27
28/** /file orc/OrcFile.hh
29 @brief The top level interface to ORC.
30*/
31
32namespace orc {
33
34 /**
35 * An abstract interface for providing ORC readers a stream of bytes.
36 */
37 class InputStream {
38 public:
39 virtual ~InputStream();
40
41 /**
42 * Get the total length of the file in bytes.
43 */
44 virtual uint64_t getLength() const = 0;
45
46 /**
47 * Get the natural size for reads.
48 * @return the number of bytes that should be read at once
49 */
50 virtual uint64_t getNaturalReadSize() const = 0;
51
52 /**
53 * Read length bytes from the file starting at offset into
54 * the buffer starting at buf.
55 * @param buf the starting position of a buffer.
56 * @param length the number of bytes to read.
57 * @param offset the position in the stream to read from.
58 */
59 virtual void read(void* buf,
60 uint64_t length,
61 uint64_t offset) = 0;
62
63 /**
64 * Get the name of the stream for error messages.
65 */
66 virtual const std::string& getName() const = 0;
67 };
68
69 /**
70 * An abstract interface for providing ORC writer a stream of bytes.
71 */
72 class OutputStream {
73 public:
74 virtual ~OutputStream();
75
76 /**
77 * Get the total length of bytes written.
78 */
79 virtual uint64_t getLength() const = 0;
80
81 /**
82 * Get the natural size for reads.
83 * @return the number of bytes that should be written at once
84 */
85 virtual uint64_t getNaturalWriteSize() const = 0;
86
87 /**
88 * Write/Append length bytes pointed by buf to the file stream
89 * @param buf the starting position of a buffer.
90 * @param length the number of bytes to write.
91 */
92 virtual void write(const void* buf, size_t length) = 0;
93
94 /**
95 * Get the name of the stream for error messages.
96 */
97 virtual const std::string& getName() const = 0;
98
99 /**
100 * Close the stream and flush any pending data to the disk.
101 */
102 virtual void close() = 0;
103 };
104
105 /**
106 * Create a stream to a local file or HDFS file if path begins with "hdfs://"
107 * @param path the name of the file in the local file system or HDFS
108 */
109 ORC_UNIQUE_PTR<InputStream> readFile(const std::string& path);
110
111 /**
112 * Create a stream to a local file.
113 * @param path the name of the file in the local file system
114 */
115 ORC_UNIQUE_PTR<InputStream> readLocalFile(const std::string& path);
116
117 /**
118 * Create a stream to an HDFS file.
119 * @param path the uri of the file in HDFS
120 */
121 ORC_UNIQUE_PTR<InputStream> readHdfsFile(const std::string& path);
122
123 /**
124 * Create a reader to the for the ORC file.
125 * @param stream the stream to read
126 * @param options the options for reading the file
127 */
128 ORC_UNIQUE_PTR<Reader> createReader(ORC_UNIQUE_PTR<InputStream> stream,
129 const ReaderOptions& options);
130 /**
131 * Create a stream to write to a local file.
132 * @param path the name of the file in the local file system
133 */
134 ORC_UNIQUE_PTR<OutputStream> writeLocalFile(const std::string& path);
135
136 /**
137 * Create a writer to write the ORC file.
138 * @param type the type of data to be written
139 * @param stream the stream to write to
140 * @param options the options for writing the file
141 */
142 ORC_UNIQUE_PTR<Writer> createWriter(
143 const Type& type,
144 OutputStream* stream,
145 const WriterOptions& options);
146}
147
148#endif
149