From: Greg Farnum Date: Tue, 13 Oct 2009 23:41:51 +0000 (-0700) Subject: Hadoop: Better document interface between CephFileSystem and libhadoopcephfs X-Git-Tag: v0.17~25 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=8d00264bf007827d802f8bbe40c2fcfd186f2ee8;p=ceph.git Hadoop: Better document interface between CephFileSystem and libhadoopcephfs --- diff --git a/src/client/hadoop/CephFSInterface.cc b/src/client/hadoop/CephFSInterface.cc index 745ae4faa87d3..81b67ff0d16b9 100644 --- a/src/client/hadoop/CephFSInterface.cc +++ b/src/client/hadoop/CephFSInterface.cc @@ -15,6 +15,12 @@ static int path_size; * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_initializeClient * Signature: (Ljava/lang/String;I)Z + * + * Performs any necessary setup to allow general use of the filesystem. + * Inputs: + * jstring args -- a command-line style input of Ceph config params + * jint block_size -- the size in bytes to use for blocks + * Returns: true on success, false otherwise */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1initializeClient (JNIEnv *env, jobject obj, jstring j_args, jint block_size) @@ -69,7 +75,8 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1i * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_getcwd * Signature: (J)Ljava/lang/String; - * Returns the current working directory. + * + * Returns the current working directory.(absolute) as a jstring */ JNIEXPORT jstring JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1getcwd (JNIEnv *env, jobject obj) @@ -95,6 +102,9 @@ JNIEXPORT jstring JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1ge * Signature: (Ljava/lang/String;)Z * * Changes the working directory. + * Inputs: + * jstring j_path: The path (relative or absolute) to switch to + * Returns: true on success, false otherwise. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1setcwd (JNIEnv *env, jobject obj, jstring j_path) @@ -112,7 +122,11 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1s * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_rmdir * Signature: (Ljava/lang/String;)Z - * Removes an empty directory. + * + * Given a path to a directory, removes the directory.if empty. + * Inputs: + * jstring j_path: The path (relative or absolute) to the directory + * Returns: true on successful delete; false otherwise */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1rmdir (JNIEnv *env, jobject, jstring j_path) @@ -149,7 +163,10 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1m * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_unlink * Signature: (Ljava/lang/String;)Z - * Unlinks a path. + * Given a path, unlinks it. + * Inputs: + * jstring j_path: The path (relative or absolute) to the file or empty dir + * Returns: true if the unlink occurred, false otherwise. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1unlink (JNIEnv *env, jobject, jstring j_path) @@ -166,7 +183,11 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1u * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_rename * Signature: (Ljava/lang/String;Ljava/lang/String;)Z - * Renames a file. + * Changes a given path name to a new name. + * Inputs: + * jstring j_from: The path whose name you want to change. + * jstring j_to: The new name for the path. + * Returns: true if the rename occurred, false otherwise */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1rename (JNIEnv *env, jobject, jstring j_from, jstring j_to) @@ -190,7 +211,8 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1r * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_exists * Signature: (Ljava/lang/String;)Z - * Returns true if the path exists. + * Returns true if it the input path exists, false + * if it does not or there is an unexpected failure. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1exists (JNIEnv *env, jobject, jstring j_path) @@ -220,9 +242,12 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1e * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_getblocksize * Signature: (Ljava/lang/String;)J - * Returns the block size. Size is -1 if the file - * does not exist. - * TODO: see if Hadoop wants something more like stripe size + * Get the block size for a given path. + * Input: + * j_string j_path: The path (relative or absolute) you want + * the block size for. + * Returns: block size (as a long) if the path exists, otherwise a negative + * number corresponding to the standard C++ error codes (which are positive). */ JNIEXPORT jlong JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1getblocksize (JNIEnv *env, jobject obj, jstring j_path) @@ -231,7 +256,7 @@ JNIEXPORT jlong JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1getb //struct stat stbuf; - jint result; + jlong result; const char *c_path = env->GetStringUTFChars(j_path, 0); if (c_path == NULL) return -ENOMEM; @@ -253,6 +278,7 @@ JNIEXPORT jlong JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1getb * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_isfile * Signature: (Ljava/lang/String;)Z + * Returns true if the given path is a file; false otherwise. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1isfile (JNIEnv *env, jobject obj, jstring j_path) @@ -278,7 +304,7 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1i * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_isdirectory * Signature: (Ljava/lang/String;)Z - * Returns true if the path is a directory. + * Returns true if the given path is a directory, false otherwise. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1isdirectory (JNIEnv *env, jobject, jstring j_path) @@ -303,7 +329,12 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1i * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_getdir * Signature: (Ljava/lang/String;)[Ljava/lang/String; - * Returns a Java array of Strings with the directory contents + * Get the contents of a given directory. + * Inputs: + * jstring j_path: The path (relative or absolute) to the directory. + * Returns: A Java String[] of the contents of the directory, or + * NULL if there is an error (ie, path is not a dir). This listing + * will not contain . or .. entries. */ JNIEXPORT jobjectArray JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1getdir (JNIEnv *env, jobject obj, jstring j_path) @@ -378,7 +409,8 @@ JNIEXPORT jobjectArray JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_cep * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_mkdirs * Signature: (Ljava/lang/String;I)I - * Create the specified directory and any required intermediate ones. + * Create the specified directory and any required intermediate ones with the + * given mode. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1mkdirs (JNIEnv *env, jobject, jstring j_path, jint mode) @@ -400,7 +432,11 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1mkdir * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_open_for_append * Signature: (Ljava/lang/String;)I - * Open a file for writing + * Open a file to append. If the file does not exist, it will be created. + * Opening a dir is possible but may have bad results. + * Inputs: + * jstring j_path: The path to open. + * Returns: a jint filehandle, or a number<0 if an error occurs. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1open_1for_1append (JNIEnv *env, jobject obj, jstring j_path) @@ -423,6 +459,10 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1open_ * Method: ceph_open_for_read * Signature: (Ljava/lang/String;)I * Open a file for reading. + * Opening a dir is possible but may have bad results. + * Inputs: + * jstring j_path: The path to open. + * Returns: a jint filehandle, or a number<0 if an error occurs. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1open_1for_1read (JNIEnv *env, jobject obj, jstring j_path) @@ -446,6 +486,11 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1open_ * Method: ceph_open_for_overwrite * Signature: (Ljava/lang/String;)I * Opens a file for overwriting; creates it if necessary. + * Opening a dir is possible but may have bad results. + * Inputs: + * jstring j_path: The path to open. + * jint mode: The mode to open with. + * Returns: a jint filehandle, or a number<0 if an error occurs. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1open_1for_1overwrite (JNIEnv *env, jobject obj, jstring j_path, jint mode) @@ -468,6 +513,7 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1open_ * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_close * Signature: (I)I + * Closes a given filehandle. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1close (JNIEnv *env, jobject ojb, jint fh) @@ -481,6 +527,12 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1close * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_setPermission * Signature: (Ljava/lang/String;I)Z + * Change the mode on a path. + * Inputs: + * jstring j_path: The path to change mode on. + * jint j_new_mode: The mode to apply. + * Returns: true if the mode is properly applied, false if there + * is any error. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1setPermission (JNIEnv *env, jobject obj, jstring j_path, jint j_new_mode) @@ -498,7 +550,8 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1s * Method: ceph_kill_client * Signature: (J)Z * - * Closes the Ceph client. + * Closes the Ceph client. This should be called before shutting down + * (multiple times is okay but redundant). */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1kill_1client (JNIEnv *env, jobject obj) @@ -511,6 +564,12 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1k * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_stat * Signature: (Ljava/lang/String;Lorg/apache/hadoop/fs/ceph/CephFileSystem/Stat;)Z + * Get the statistics on a path returned in a custom format defined + * in CephFileSystem. + * Inputs: + * jstring j_path: The path to stat. + * jobject j_stat: The stat object to fill. + * Returns: true if the stat is successful, false otherwise. */ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1stat (JNIEnv *env, jobject obj, jstring j_path, jobject j_stat) @@ -558,6 +617,11 @@ JNIEXPORT jboolean JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1s * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_statfs * Signature: (Ljava/lang/String;Lorg/apache/hadoop/fs/ceph/CephFileSystem/CephStat;)I + * Statfs a filesystem in a custom format defined in CephFileSystem. + * Inputs: + * jstring j_path: A path on the filesystem that you wish to stat. + * jobject j_ceph_stat: The CephStat object to fill. + * Returns: true if successful and the CephStat is filled; false otherwise. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1statfs (JNIEnv *env, jobject obj, jstring j_path, jobject j_cephstat) @@ -593,6 +657,11 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1statf * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_replication * Signature: (Ljava/lang/String;)I + * Check how many times a path should be replicated (if it is + * degraded it may not actually be replicated this often). + * Inputs: + * jstring j_path: The path to check. + * Returns: an int containing the number of times replicated. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1replication (JNIEnv *env, jobject obj, jstring j_path) @@ -609,6 +678,11 @@ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1repli * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_hosts * Signature: (IJ)Ljava/lang/String; + * Find the IP:port addresses of the primary OSD for a given file and offset. + * Inputs: + * jint j_fh: The filehandle for the file. + * jlong j_offset: The offset to get the location of. + * Returns: a jstring of the location as IP, or NULL if there is an error. */ JNIEXPORT jstring JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1hosts (JNIEnv *env, jobject obj, jint j_fh, jlong j_offset) @@ -635,6 +709,12 @@ JNIEXPORT jstring JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1ho * Class: org_apache_hadoop_fs_ceph_CephFileSystem * Method: ceph_setTimes * Signature: (Ljava/lang/String;JJ)I + * Set the mtime and atime for a given path. + * Inputs: + * jstring j_path: The path to set the times for. + * jlong mtime: The mtime to set, in millis since epoch (-1 to not set). + * jlong atime: The atime to set, in millis since epoch (-1 to not set) + * Returns: 0 if successful, an error code otherwise. */ JNIEXPORT jint JNICALL Java_org_apache_hadoop_fs_ceph_CephFileSystem_ceph_1setTimes (JNIEnv *env, jobject obj, jstring j_path, jlong mtime, jlong atime) diff --git a/src/client/hadoop/ceph/CephFileSystem.java b/src/client/hadoop/ceph/CephFileSystem.java index 1cd7a1e237417..e41f86ee6c2c7 100644 --- a/src/client/hadoop/ceph/CephFileSystem.java +++ b/src/client/hadoop/ceph/CephFileSystem.java @@ -74,28 +74,167 @@ public class CephFileSystem extends FileSystem { private boolean debug = false; private String fs_default_name; + /* + * Performs any necessary setup to allow general use of the filesystem. + * Inputs: + * String argsuments -- a command-line style input of Ceph config params + * int block_size -- the size in bytes to use for blocks + * Returns: true on success, false otherwise + */ private native boolean ceph_initializeClient(String arguments, int block_size); - private native String ceph_getcwd(); + + /* + * Returns the current working directory.(absolute) as a String + */ + private native String ceph_getcwd(); + /* + * Changes the working directory. + * Inputs: + * String path: The path (relative or absolute) to switch to + * Returns: true on success, false otherwise. + */ private native boolean ceph_setcwd(String path); + /* + * Given a path to a directory, removes the directory.if empty. + * Inputs: + * jstring j_path: The path (relative or absolute) to the directory + * Returns: true on successful delete; false otherwise + */ private native boolean ceph_rmdir(String path); + /* + * Given a path, unlinks it. + * Inputs: + * String path: The path (relative or absolute) to the file or empty dir + * Returns: true if the unlink occurred, false otherwise. + */ private native boolean ceph_unlink(String path); + /* + * Changes a given path name to a new name. + * Inputs: + * jstring j_from: The path whose name you want to change. + * jstring j_to: The new name for the path. + * Returns: true if the rename occurred, false otherwise + */ private native boolean ceph_rename(String old_path, String new_path); + /* + * Returns true if it the input path exists, false + * if it does not or there is an unexpected failure. + */ private native boolean ceph_exists(String path); - private native long ceph_getblocksize(String path); + /* + * Get the block size for a given path. + * Input: + * String path: The path (relative or absolute) you want + * the block size for. + * Returns: block size if the path exists, otherwise a negative number + * corresponding to the standard C++ error codes (which are positive). + */ + private native long ceph_getblocksize(String path); + /* + * Returns true if the given path is a directory, false otherwise. + */ private native boolean ceph_isdirectory(String path); + /* + * Returns true if the given path is a file; false otherwise. + */ private native boolean ceph_isfile(String path); + /* + * Get the contents of a given directory. + * Inputs: + * String path: The path (relative or absolute) to the directory. + * Returns: A Java String[] of the contents of the directory, or + * NULL if there is an error (ie, path is not a dir). This listing + * will not contain . or .. entries. + */ private native String[] ceph_getdir(String path); + /* + * Create the specified directory and any required intermediate ones with the + * given mode. + */ private native int ceph_mkdirs(String path, int mode); + /* + * Open a file to append. If the file does not exist, it will be created. + * Opening a dir is possible but may have bad results. + * Inputs: + * String path: The path to open. + * Returns: an int filehandle, or a number<0 if an error occurs. + */ private native int ceph_open_for_append(String path); + /* + * Open a file for reading. + * Opening a dir is possible but may have bad results. + * Inputs: + * String path: The path to open. + * Returns: an int filehandle, or a number<0 if an error occurs. + */ private native int ceph_open_for_read(String path); + /* + * Opens a file for overwriting; creates it if necessary. + * Opening a dir is possible but may have bad results. + * Inputs: + * String path: The path to open. + * int mode: The mode to open with. + * Returns: an int filehandle, or a number<0 if an error occurs. + */ private native int ceph_open_for_overwrite(String path, int mode); + /* + * Closes a given filehandle. + */ private native int ceph_close(int filehandle); + /* + * Change the mode on a path. + * Inputs: + * String path: The path to change mode on. + * int mode: The mode to apply. + * Returns: true if the mode is properly applied, false if there + * is any error. + */ private native boolean ceph_setPermission(String path, int mode); + /* + * Closes the Ceph client. This should be called before shutting down + * (multiple times is okay but redundant). + */ private native boolean ceph_kill_client(); + /* + * Get the statistics on a path returned in a custom format defined below. + * Inputs: + * String path: The path to stat. + * Stat fill: The stat object to fill. + * Returns: true if the stat is successful, false otherwise. + */ private native boolean ceph_stat(String path, Stat fill); + /* + * Statfs a filesystem in a custom format defined in CephFileSystem. + * Inputs: + * String path: A path on the filesystem that you wish to stat. + * CephStat fill: The CephStat object to fill. + * Returns: true if successful and the CephStat is filled; false otherwise. + */ private native int ceph_statfs(String Path, CephStat fill); + /* + * Check how many times a path should be replicated (if it is + * degraded it may not actually be replicated this often). + * Inputs: + * String path: The path to check. + * Returns: an int containing the number of times replicated. + */ private native int ceph_replication(String path); + /* + * Find the IP:port addresses of the primary OSD for a given file and offset. + * Inputs: + * int fh: The filehandle for the file. + * long offset: The offset to get the location of. + * Returns: a String of the location as IP, or NULL if there is an error. + */ private native String ceph_hosts(int fh, long offset); + /* + * Set the mtime and atime for a given path. + * Inputs: + * String path: The path to set the times for. + * long mtime: The mtime to set, in millis since epoch (-1 to not set). + * long atime: The atime to set, in millis since epoch (-1 to not set) + * Returns: 0 if successful, an error code otherwise. + */ private native int ceph_setTimes(String path, long mtime, long atime); /**