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