dmlite  0.6
catalog.h
Go to the documentation of this file.
1 /// @file include/dmlite/cpp/catalog.h
2 /// @brief Catalog API.
3 /// @author Alejandro Álvarez Ayllón <aalvarez@cern.ch>
4 #ifndef DMLITE_CPP_CATALOG_H
5 #define DMLITE_CPP_CATALOG_H
6 
7 #include "dmlite/common/config.h"
8 #include "base.h"
9 #include "exceptions.h"
10 #include "status.h"
11 #include "inode.h"
12 #include "utils/extensible.h"
13 
14 #include <dirent.h>
15 #include <sys/stat.h>
16 #include <string>
17 #include <vector>
18 #include <utime.h>
19 
20 namespace dmlite {
21 
22  // Forward declarations.
23  class StackInstance;
24  class PluginManager;
25 
26  /// Typedef for directories.
27  struct Directory { virtual ~Directory(); };
28 
29  /// Interface for Catalog (Namespaces).
30  class Catalog: public virtual BaseInterface {
31  public:
32  /// Destructor.
33  virtual ~Catalog();
34 
35  /// Change the working dir. Future not-absolute paths will use this as root.
36  /// @param path The new working dir.
37  virtual void changeDir(const std::string& path) ;
38 
39  /// Get the current working dir.
40  /// @return The current working dir.
41  virtual std::string getWorkingDir(void) ;
42 
43  /// Do an extended stat of a file or directory.
44  /// @param path The path of the file or directory.
45  /// @param followSym If true, symlinks will be followed.
46  /// @return The extended status of the file.
47  virtual ExtendedStat extendedStat(const std::string& path,
48  bool followSym = true) ;
49 
50  /// Do an extended stat of a file or directory. Exception-safe version, returns a status
51  /// @param path The path of the file or directory.
52  /// @param followSym If true, symlinks will be followed.
53  /// @param xstat The extended status of the file.
54  /// @return A status object
55  virtual DmStatus extendedStat(ExtendedStat &xstat,
56  const std::string& path,
57  bool followSym = true) ;
58 
59  /// Do an extended stat of a logical file using an associated replica file name.
60  /// @param rfn The replica.
61  /// @return The extended status of the file.
62  virtual ExtendedStat extendedStatByRFN(const std::string& rfn) ;
63 
64  /// Checks wether the process would be allowed to read, write, or check existence.
65  /// @param lfn Logical filename.
66  /// @param mode A mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
67  /// @return true if the file can be accessed.
68  /// @note If the file does not exist, an exception will be thrown.
69  virtual bool access(const std::string& path, int mode) ;
70 
71  /// Checks wether the process would be allowed to read, write, or check existence.
72  /// @param rfn Replica filename.
73  /// @param mode A mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
74  /// @return true if the file can be accessed.
75  /// @note If the file does not exist, an exception will be thrown.
76  virtual bool accessReplica(const std::string& replica, int mode) ;
77 
78  /// Add a new replica for a file.
79  /// @param replica Stores the data that is going to be added. fileid must
80  /// point to the id of the logical file in the catalog.
81  virtual void addReplica(const Replica& replica) ;
82 
83  /// Delete a replica.
84  /// @param replica The replica to remove.
85  virtual void deleteReplica(const Replica& replica) ;
86 
87  /// Get replicas for a file.
88  /// @param path The file for which replicas will be retrieved.
89  virtual std::vector<Replica> getReplicas(const std::string& path) ;
90 
91  /// Creates a new symlink.
92  /// @param path The existing path.
93  /// @param symlink The new access path.
94  virtual void symlink(const std::string& path,
95  const std::string& symlink) ;
96 
97  /// Returns the path pointed by the symlink path
98  /// @param path The symlink file.
99  /// @return The symlink target.
100  virtual std::string readLink(const std::string& path) ;
101 
102  /// Remove a file.
103  /// @param path The path to remove.
104  virtual void unlink(const std::string& path) ;
105 
106  /// Creates an entry in the catalog.
107  /// @param path The new file.
108  /// @param mode The creation mode.
109  virtual void create(const std::string& path,
110  mode_t mode) ;
111 
112  /// Sets the calling process’s file mode creation mask to mask & 0777.
113  /// @param mask The new mask.
114  /// @return The value of the previous mask.
115  virtual mode_t umask(mode_t mask);
116 
117  /// Set the mode of a file.
118  /// @param path The file to modify.
119  /// @param mode The new mode as an integer (i.e. 0755)
120  virtual void setMode(const std::string& path,
121  mode_t mode) ;
122 
123  /// Set the owner of a file.
124  /// @param path The file to modify.
125  /// @param newUid The uid of the new owneer.
126  /// @param newGid The gid of the new group.
127  /// @param followSymLink If set to true, symbolic links will be followed.
128  virtual void setOwner(const std::string& path, uid_t newUid, gid_t newGid,
129  bool followSymLink = true) ;
130 
131  /// Set the size of a file.
132  /// @param path The file to modify.
133  /// @param newSize The new file size.
134  virtual void setSize(const std::string& path,
135  size_t newSize) ;
136 
137  /// Set the checksum of a file.
138  /// @param path The file to modify.
139  /// @param csumtype The checksum type cc
140  /// @param csumvalue The checksum value.
141  virtual void setChecksum(const std::string& path,
142  const std::string& csumtype,
143  const std::string& csumvalue) ;
144 
145  /// Get the checksum of a file, eventually waiting for it to be calculated.
146  /// @param path The file to query
147  /// @param csumtype The checksum type (CS, AD or MD. We can also pass a long checksum name (e.g. checksum.adler32)).
148  /// @param csumvalue The checksum value.
149  /// @param forcerecalc Force recalculation of the checksum (may take long and throw EAGAIN)
150  /// @param waitsecs Seconds to wait for a checksum to be calculated. Throws EAGAIN if timeouts. Set to 0 for blocking behavior.
151  virtual void getChecksum(const std::string& path,
152  const std::string& csumtype,
153  std::string& csumvalue,
154  const std::string& pfn, const bool forcerecalc = false, const int waitsecs = 0) ;
155 
156  /// Set the ACLs
157  /// @param path The file to modify.
158  /// @param acl The Access Control List.
159  virtual void setAcl(const std::string& path,
160  const Acl& acl) ;
161 
162  /// Set access and/or modification time.
163  /// @param path The file path.
164  /// @param buf A struct holding the new times.
165  virtual void utime(const std::string& path,
166  const struct utimbuf* buf) ;
167 
168  /// Get the comment associated with a file.
169  /// @param path The file or directory.
170  /// @return The associated comment.
171  virtual std::string getComment(const std::string& path) ;
172 
173  /// Set the comment associated with a file.
174  /// @param path The file or directory.
175  /// @param comment The new comment.
176  virtual void setComment(const std::string& path,
177  const std::string& comment) ;
178 
179  /// Set GUID of a file.
180  /// @param path The file.
181  /// @param guid The new GUID.
182  virtual void setGuid(const std::string& path,
183  const std::string &guid) ;
184 
185  /// Update extended metadata on the catalog.
186  /// @param path The file to update.
187  /// @param attr The extended attributes struct.
188  virtual void updateExtendedAttributes(const std::string& path,
189  const Extensible& attr) ;
190 
191  /// Open a directory for reading.
192  /// @param path The directory to open.
193  /// @return A pointer to a handle that can be used for later calls.
194  virtual Directory* openDir(const std::string& path) ;
195 
196  /// Close a directory opened previously.
197  /// @param dir The directory handle as returned by NsInterface::openDir.
198  virtual void closeDir(Directory* dir) ;
199 
200  /// Read next entry from a directory (simple read).
201  /// @param dir The directory handle as returned by NsInterface::openDir.
202  /// @return 0x00 on failure or end of directory.
203  virtual struct dirent* readDir(Directory* dir) ;
204 
205  /// Read next entry from a directory (stat information added).
206  /// @param dir The directory handle as returned by NsInterface::openDir.
207  /// @return 0x00 on failure (and errno is set) or end of directory.
208  virtual ExtendedStat* readDirx(Directory* dir) ;
209 
210  /// Create a new empty directory.
211  /// @param path The path of the new directory.
212  /// @param mode The creation mode.
213  virtual void makeDir(const std::string& path,
214  mode_t mode) ;
215 
216  /// Rename a file or directory.
217  /// @param oldPath The old name.
218  /// @param newPath The new name.
219  virtual void rename(const std::string& oldPath,
220  const std::string& newPath) ;
221 
222  /// Remove a directory.
223  /// @param path The path of the directory to remove.
224  virtual void removeDir(const std::string& path) ;
225 
226  /// Get a replica.
227  /// @param rfn The replica file name.
228  virtual Replica getReplicaByRFN(const std::string& rfn) ;
229 
230  /// Update a replica.
231  /// @param replica The replica to modify.
232  /// @return 0 on success, error code otherwise.
233  virtual void updateReplica(const Replica& replica) ;
234  };
235 
236  /// Plug-ins must implement a concrete factory to be instantiated.
237  class CatalogFactory: public virtual BaseFactory {
238  public:
239  /// Virtual destructor
240  virtual ~CatalogFactory();
241 
242  protected:
243  // Stack instance is allowed to instantiate catalogs
244  friend class StackInstance;
245 
246  /// Children of CatalogFactory are allowed to instantiate too (decorator)
247  static Catalog* createCatalog(CatalogFactory* factory,
248  PluginManager* pm) ;
249 
250  /// Instantiate a implementation of Catalog
251  virtual Catalog* createCatalog(PluginManager* pm) ;
252  };
253 
254 };
255 
256 #endif // DMLITE_CPP_CATALOG_H
virtual ExtendedStat extendedStat(const std::string &path, bool followSym=true)
virtual void makeDir(const std::string &path, mode_t mode)
Base class for interfaces.
Definition: base.h:18
virtual bool access(const std::string &path, int mode)
virtual ExtendedStat extendedStatByRFN(const std::string &rfn)
Definition: status.h:17
Plug-ins must implement a concrete factory to be instantiated.
Definition: catalog.h:237
virtual ~CatalogFactory()
Virtual destructor.
Definition: dmlite.h:161
virtual Directory * openDir(const std::string &path)
virtual std::string getWorkingDir(void)
virtual void setMode(const std::string &path, mode_t mode)
virtual struct dirent * readDir(Directory *dir)
virtual std::string getComment(const std::string &path)
CatalogInterface can only be instantiated through this class.
Definition: dmlite.h:42
virtual void rename(const std::string &oldPath, const std::string &newPath)
virtual void changeDir(const std::string &path)
virtual bool accessReplica(const std::string &replica, int mode)
Interface for Catalog (Namespaces).
Definition: catalog.h:30
virtual void setGuid(const std::string &path, const std::string &guid)
virtual void setOwner(const std::string &path, uid_t newUid, gid_t newGid, bool followSymLink=true)
static Catalog * createCatalog(CatalogFactory *factory, PluginManager *pm)
Children of CatalogFactory are allowed to instantiate too (decorator)
virtual std::string readLink(const std::string &path)
virtual void deleteReplica(const Replica &replica)
Exceptions used by the API.
virtual void addReplica(const Replica &replica)
Base class for factories.
Definition: base.h:48
virtual void setSize(const std::string &path, size_t newSize)
virtual void setAcl(const std::string &path, const Acl &acl)
virtual void unlink(const std::string &path)
virtual void closeDir(Directory *dir)
virtual void create(const std::string &path, mode_t mode)
Extensible types (hold metadata).
File replica metadata.
Definition: inode.h:73
File/directory metadata.
Definition: inode.h:29
virtual void setChecksum(const std::string &path, const std::string &csumtype, const std::string &csumvalue)
Status objects used by the API.
virtual std::vector< Replica > getReplicas(const std::string &path)
Helpful typedef for KeyValue containers.
Definition: extensible.h:20
virtual ~Catalog()
Destructor.
Definition: security.h:52
Base interfaces.
virtual void symlink(const std::string &path, const std::string &symlink)
virtual void setComment(const std::string &path, const std::string &comment)
virtual void getChecksum(const std::string &path, const std::string &csumtype, std::string &csumvalue, const std::string &pfn, const bool forcerecalc=false, const int waitsecs=0)
virtual void removeDir(const std::string &path)
virtual void utime(const std::string &path, const struct utimbuf *buf)
virtual void updateExtendedAttributes(const std::string &path, const Extensible &attr)
virtual ExtendedStat * readDirx(Directory *dir)
Low-level access API.
virtual void updateReplica(const Replica &replica)
virtual Replica getReplicaByRFN(const std::string &rfn)
virtual ~Directory()
virtual mode_t umask(mode_t mask)
Typedef for directories.
Definition: catalog.h:27