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_FILESYSTEM_H_
29#define _HDFS_LIBHDFS3_CLIENT_FILESYSTEM_H_
30
31#include "BlockLocation.h"
32#include "DirectoryIterator.h"
33#include "FileStatus.h"
34#include "FileSystemStats.h"
35#include "Permission.h"
36#include "XmlConfig.h"
37
38#include <vector>
39
40namespace Hdfs {
41namespace Internal {
42struct FileSystemWrapper;
43}
44
45class FileSystem {
46public:
47
48 /**
49 * Construct a FileSystem
50 * @param conf hdfs configuration
51 */
52 FileSystem(const Config & conf);
53
54 /**
55 * Copy construct of FileSystem
56 */
57 FileSystem(const FileSystem & other);
58
59 /**
60 * Assign operator of FileSystem
61 */
62 FileSystem & operator = (const FileSystem & other);
63
64 /**
65 * Destroy a HdfsFileSystem instance
66 */
67 ~FileSystem();
68
69 /**
70 * Connect to default hdfs.
71 */
72 void connect();
73
74 /**
75 * Connect to hdfs
76 * @param uri hdfs connection uri, hdfs://host:port
77 */
78 void connect(const char * uri);
79
80 /**
81 * Connect to hdfs with user or token
82 * username and token cannot be set at the same time
83 * @param uri connection uri.
84 * @param username user used to connect to hdfs
85 * @param token token used to connect to hdfs
86 */
87 void connect(const char * uri, const char * username, const char * token);
88
89 /**
90 * disconnect from hdfs
91 */
92 void disconnect();
93
94 /**
95 * To get default number of replication.
96 * @return the default number of replication.
97 */
98 int getDefaultReplication() const;
99
100 /**
101 * To get the default number of block size.
102 * @return the default block size.
103 */
104 int64_t getDefaultBlockSize() const;
105
106 /**
107 * To get the home directory.
108 * @return home directory.
109 */
110 std::string getHomeDirectory() const;
111
112 /**
113 * To delete a file or directory.
114 * @param path the path to be deleted.
115 * @param recursive if path is a directory, delete the contents recursively.
116 * @return return true if success.
117 */
118 bool deletePath(const char * path, bool recursive);
119
120 /**
121 * To create a directory which given permission.
122 * @param path the directory path which is to be created.
123 * @param permission directory permission.
124 * @return return true if success.
125 */
126 bool mkdir(const char * path, const Permission & permission);
127
128 /**
129 * To create a directory which given permission.
130 * If parent path does not exits, create it.
131 * @param path the directory path which is to be created.
132 * @param permission directory permission.
133 * @return return true if success.
134 */
135 bool mkdirs(const char * path, const Permission & permission);
136
137 /**
138 * To get path information.
139 * @param path the path which information is to be returned.
140 * @return the path information.
141 */
142 FileStatus getFileStatus(const char * path) const;
143
144 /**
145 * Return an array containing hostnames, offset and size of
146 * portions of the given file.
147 *
148 * This call is most helpful with DFS, where it returns
149 * hostnames of machines that contain the given file.
150 *
151 * The FileSystem will simply return an elt containing 'localhost'.
152 *
153 * @param path path is used to identify an FS since an FS could have
154 * another FS that it could be delegating the call to
155 * @param start offset into the given file
156 * @param len length for which to get locations for
157 */
158 std::vector<BlockLocation> getFileBlockLocations(const char * path,
159 int64_t start, int64_t len);
160
161 /**
162 * list the contents of a directory.
163 * @param path The directory path.
164 * @return Return a iterator to visit all elements in this directory.
165 */
166 DirectoryIterator listDirectory(const char * path);
167
168 /**
169 * list all the contents of a directory.
170 * @param path The directory path.
171 * @return Return a vector of file informations in the directory.
172 */
173 std::vector<FileStatus> listAllDirectoryItems(const char * path);
174
175 /**
176 * To set the owner and the group of the path.
177 * username and groupname cannot be empty at the same time.
178 * @param path the path which owner of group is to be changed.
179 * @param username new user name.
180 * @param groupname new group.
181 */
182 void setOwner(const char * path, const char * username,
183 const char * groupname);
184
185 /**
186 * To set the access time or modification time of a path.
187 * @param path the path which access time or modification time is to be changed.
188 * @param mtime new modification time.
189 * @param atime new access time.
190 */
191 void setTimes(const char * path, int64_t mtime, int64_t atime);
192
193 /**
194 * To set the permission of a path.
195 * @param path the path which permission is to be changed.
196 * @param permission new permission.
197 */
198 void setPermission(const char * path, const Permission & permission);
199
200 /**
201 * To set the number of replication.
202 * @param path the path which number of replication is to be changed.
203 * @param replication new number of replication.
204 * @return return true if success.
205 */
206 bool setReplication(const char * path, short replication);
207
208 /**
209 * To rename a path.
210 * @param src old path.
211 * @param dst new path.
212 * @return return true if success.
213 */
214 bool rename(const char * src, const char * dst);
215
216 /**
217 * To set working directory.
218 * @param path new working directory.
219 */
220 void setWorkingDirectory(const char * path);
221
222 /**
223 * To get working directory.
224 * @return working directory.
225 */
226 std::string getWorkingDirectory() const;
227
228 /**
229 * To test if the path exist.
230 * @param path the path which is to be tested.
231 * @return return true if the path exist.
232 */
233 bool exist(const char * path) const;
234
235 /**
236 * To get the file system status.
237 * @return the file system status.
238 */
239 FileSystemStats getStats() const;
240
241 /**
242 * Truncate the file in the indicated path to the indicated size.
243 * @param src The path to the file to be truncated
244 * @param size The size the file is to be truncated to
245 *
246 * @return true if and client does not need to wait for block recovery,
247 * false if client needs to wait for block recovery.
248 */
249 bool truncate(const char * src, int64_t size);
250
251 /**
252 * Get a valid Delegation Token.
253 *
254 * @param renewer the designated renewer for the token
255 * @return Token string
256 * @throws IOException
257 */
258 std::string getDelegationToken(const char * renewer);
259
260 /**
261 * Get a valid Delegation Token using the default user as renewer.
262 *
263 * @return Token string
264 * @throws IOException
265 */
266 std::string getDelegationToken();
267
268 /**
269 * Renew an existing delegation token.
270 *
271 * @param token delegation token obtained earlier
272 * @return the new expiration time
273 * @throws IOException
274 */
275 int64_t renewDelegationToken(const std::string & token);
276
277 /**
278 * Cancel an existing delegation token.
279 *
280 * @param token delegation token
281 * @throws IOException
282 */
283 void cancelDelegationToken(const std::string & token);
284
285private:
286 Config conf;
287 Internal::FileSystemWrapper * impl;
288
289 friend class InputStream;
290 friend class OutputStream;
291};
292
293}
294#endif /* _HDFS_LIBHDFS3_CLIENT_FILESYSTEM_H_ */
295