1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18// Implement Arrow JSON serialization format
19
20#ifndef ARROW_IPC_JSON_H
21#define ARROW_IPC_JSON_H
22
23#include <memory>
24#include <string>
25
26#include "arrow/status.h"
27#include "arrow/util/visibility.h"
28
29namespace arrow {
30
31class Buffer;
32class MemoryPool;
33class RecordBatch;
34class Schema;
35
36namespace ipc {
37namespace internal {
38namespace json {
39
40/// \class JsonWriter
41/// \brief Write the JSON representation of an Arrow record batch file or stream
42///
43/// This is used for integration testing
44class ARROW_EXPORT JsonWriter {
45 public:
46 ~JsonWriter();
47
48 /// \brief Create a new JSON writer that writes to memory
49 ///
50 /// \param[in] schema the schema of record batches
51 /// \param[out] out the returned writer object
52 /// \return Status
53 static Status Open(const std::shared_ptr<Schema>& schema,
54 std::unique_ptr<JsonWriter>* out);
55
56 /// \brief Append a record batch
57 Status WriteRecordBatch(const RecordBatch& batch);
58
59 /// \brief Finish the JSON payload and return as a std::string
60 ///
61 /// \param[out] result the JSON as as a std::string
62 /// \return Status
63 Status Finish(std::string* result);
64
65 private:
66 explicit JsonWriter(const std::shared_ptr<Schema>& schema);
67
68 // Hide RapidJSON details from public API
69 class JsonWriterImpl;
70 std::unique_ptr<JsonWriterImpl> impl_;
71};
72
73/// \class JsonReader
74/// \brief Read the JSON representation of an Arrow record batch file or stream
75///
76/// This is used for integration testing
77class ARROW_EXPORT JsonReader {
78 public:
79 ~JsonReader();
80
81 /// \brief Create a new JSON reader
82 ///
83 /// \param[in] pool a MemoryPool to use for buffer allocations
84 /// \param[in] data a Buffer containing the JSON data
85 /// \param[out] reader the returned reader object
86 /// \return Status
87 static Status Open(MemoryPool* pool, const std::shared_ptr<Buffer>& data,
88 std::unique_ptr<JsonReader>* reader);
89
90 /// \brief Create a new JSON reader that uses the default memory pool
91 ///
92 /// \param[in] data a Buffer containing the JSON data
93 /// \param[out] reader the returned reader object
94 /// \return Status
95 static Status Open(const std::shared_ptr<Buffer>& data,
96 std::unique_ptr<JsonReader>* reader);
97
98 /// \brief Return the schema read from the JSON
99 std::shared_ptr<Schema> schema() const;
100
101 /// \brief Return the number of record batches
102 int num_record_batches() const;
103
104 /// \brief Read a particular record batch from the file
105 ///
106 /// \param[in] i the record batch index, does not boundscheck
107 /// \param[out] batch the read record batch
108 Status ReadRecordBatch(int i, std::shared_ptr<RecordBatch>* batch) const;
109
110 private:
111 JsonReader(MemoryPool* pool, const std::shared_ptr<Buffer>& data);
112
113 // Hide RapidJSON details from public API
114 class JsonReaderImpl;
115 std::unique_ptr<JsonReaderImpl> impl_;
116};
117
118} // namespace json
119} // namespace internal
120} // namespace ipc
121} // namespace arrow
122
123#endif // ARROW_IPC_JSON_H
124