1/********************************************************************
2 * Copyright (c) 2013 - 2014, Pivotal Inc.
3 * All rights reserved.
4 *
5 * Author: Zhanwei Wang
6 ********************************************************************/
7/********************************************************************
8 * 2014 -
9 * open source under Apache License Version 2.0
10 ********************************************************************/
11/**
12 * Licensed to the Apache Software Foundation (ASF) under one
13 * or more contributor license agreements. See the NOTICE file
14 * distributed with this work for additional information
15 * regarding copyright ownership. The ASF licenses this file
16 * to you under the Apache License, Version 2.0 (the
17 * "License"); you may not use this file except in compliance
18 * with the License. You may obtain a copy of the License at
19 *
20 * http://www.apache.org/licenses/LICENSE-2.0
21 *
22 * Unless required by applicable law or agreed to in writing, software
23 * distributed under the License is distributed on an "AS IS" BASIS,
24 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25 * See the License for the specific language governing permissions and
26 * limitations under the License.
27 */
28#ifndef _HDFS_LIBHDFS3_CLIENT_OUTPUTSTREAM_H_
29#define _HDFS_LIBHDFS3_CLIENT_OUTPUTSTREAM_H_
30
31#include "FileSystem.h"
32
33namespace Hdfs {
34
35/**
36 * Use the CreateFlag as follows:
37 * <ol>
38 * <li> CREATE - to create a file if it does not exist,
39 * else throw FileAlreadyExists.</li>
40 * <li> APPEND - to append to a file if it exists,
41 * else throw FileNotFoundException.</li>
42 * <li> OVERWRITE - to truncate a file if it exists,
43 * else throw FileNotFoundException.</li>
44 * <li> CREATE|APPEND - to create a file if it does not exist,
45 * else append to an existing file.</li>
46 * <li> CREATE|OVERWRITE - to create a file if it does not exist,
47 * else overwrite an existing file.</li>
48 * <li> SyncBlock - to force closed blocks to the disk device.
49 * In addition {@link OutputStream::sync()} should be called after each write,
50 * if true synchronous behavior is required.</li>
51 * </ol>
52 *
53 * Following combination is not valid and will result in
54 * {@link InvalidParameter}:
55 * <ol>
56 * <li> APPEND|OVERWRITE</li>
57 * <li> CREATE|APPEND|OVERWRITE</li>
58 * </ol>
59 */
60enum CreateFlag {
61 Create = 0x01, Overwrite = 0x02, Append = 0x04, SyncBlock = 0x08
62};
63
64namespace Internal {
65class OutputStreamInter;
66}
67
68/**
69 * A output stream used to write data to hdfs.
70 */
71class OutputStream {
72public:
73 /**
74 * Construct a new OutputStream.
75 */
76 OutputStream();
77 /**
78 * Destroy a OutputStream instance.
79 */
80 ~OutputStream();
81
82 /**
83 * To create or append a file.
84 * @param fs hdfs file system.
85 * @param path the file path.
86 * @param flag creation flag, can be Create, Append or Create|Overwrite.
87 * @param permission create a new file with given permission.
88 * @param createParent if the parent does not exist, create it.
89 * @param replication create a file with given number of replication.
90 * @param blockSize create a file with given block size.
91 */
92 void open(FileSystem & fs, const char * path, int flag = Create,
93 const Permission permission = Permission(0644), bool createParent =
94 false, int replication = 0, int64_t blockSize = 0);
95
96 /**
97 * To append data to file.
98 * @param buf the data used to append.
99 * @param size the data size.
100 */
101 void append(const char * buf, int64_t size);
102
103 /**
104 * Flush all data in buffer and waiting for ack.
105 * Will block until get all acks.
106 */
107 void flush();
108
109 /**
110 * return the current file length.
111 * @return current file length.
112 */
113 int64_t tell();
114
115 /**
116 * the same as flush right now.
117 */
118 void sync();
119
120 /**
121 * close the stream.
122 */
123 void close();
124
125private:
126 Internal::OutputStreamInter * impl;
127
128};
129
130}
131
132#endif /* _HDFS_LIBHDFS3_CLIENT_OUTPUTSTREAM_H_ */
133