• Introduction
• Add data
• From a data stream
• From a local file
• Get file information
• Get a file
• To data stream
• To a local file
• To a file descriptor
• Delete a file
• Rename a file
• Get a list of files
• Error management

Introduction

This development guide will explain to you how to write an application that access to data on a FineFS cluster.

Any operation will begins by instanciating a FineFS object:

<?php

// library include
require_once("/path/to/finefs/lib/php/class.FineFS.php");

// object instance creation
$finefs = FineFS::factory(); // or FineFS::singleton();

Add data

From a data stream

The putData() method creates or updates a file on the cluster, filling it with the data given in parameter.

• Simple example

// name of the file on the cluster
$filename = "public/data/testfile";
// content of the file
$content = "any binary content";
// file creation
$finefs->putData($filename, $content);

?>

• With metadata

// hash of metadata
$meta = array(
        "color"    => "blue",
        "mimetype" => "text/plain"
);
// name of the file on the cluster
$filename = "public/data/testfile-meta";
// content of the file
$content = "any binary content";
// file creation
$finefs->putData($filename, $content, $meta);

?>

From a local file

The putFile() method creates or updates a file on the cluster, filling it with the content of a local file.

• Simple example

// name of the file on the cluster
$filename = "public/data/testfile";
// path to the source file on the local filesystem
$path = "/path/to/source/file";
// file creation
$finefs->putFile($filename, $path);

?>

• With metadata

// hash of metadata
$meta = array(
        "color"    => "blue",
        "mimetype" => "text/plain"
);
// name of the file on the cluster
$filename = "public/data/testfile-meta";
// path to the source file on the local filesystem
$path = "/path/to/source/file";
// file creation
$finefs->putFile($filename, $path);

?>

Get file information

The getInfo() method returns a hash which contains a key for each metadata, and the keys "origin" (originator host of the file), "id" (unique identifier of the file), "date" (creation date), "size" (file's size in bytes) and "md5" (MD5sum of the file).

// name of the file on the cluster
$filename = "public/data/testfile-meta";
// fetching info
$info = $finefs->getInfo($filename);
// writing info
print_r($info);

?>

Output:

Array
(
    [color] => blue
    [mimetype] => text/plain
    [origin] => hostname
    [id] => fdd47d661567c74e9ae7f9fe3cc16f4a
    [date] => 2009-07-31T14:59:09+02:00
    [size] => 18
    [md5] => 9db708a207436fd6400aae2861194a49
)

Get a file

To data stream

The getData() method returns the same hash than getInfo(), plus a "data" key which contains the content of the file.

// name of the file on the cluster
$filename = "public/data/testfile-meta";
// get file's data
$file = $finefs->getData($filename);
// show data
print_r($file);

?>

Output:

Array
(
    [color] => blue
    [mimetype] => text/plain
    [origin] => hostname
    [id] => ffd55a4999401d90be5173c5f7048537
    [date] => 2009-07-31T15:00:46+02:00
    [size] => 18
    [md5] => 9db708a207436fd6400aae2861194a49
    [data] => any binary content
)

To a local file

The getFile() method returns the same hash as getInfo(), and write the file content to the desired path.

// name of the file on the cluster
$filename = "public/data/testfile-meta";
// path to the local destination
$path = "/path/to/another/local/file";
// get the file
$finefs->getFile($filename, $path);

?>

To a file descriptor

The getFileOnDescriptor() method returns the same hash as getInfo(), and write the file content to the desired path.

// open a file descriptor
$fp = fopen("/path/to/another/local/file", "w");
// write the content of the file on the descriptor
$finefs->getFileOnDescriptor("public/data/testfile-meta", $fp);
// close the file descriptor
fclose($fp);

?>

It could be used to write content directly to the standard output:

$finefs->getFileOnDescriptor("public/data/testfile-meta", STDOUT);

?>

Delete a file

The remove() method deletes the given file from the cluster.

$finefs->remove("public/data/testfile-meta");

?>

Rename a file

The rename() method moves or renames a file on the cluster.

// current name of the file
$from = "public/data/testfile-meta";
// new name
$to = "private/data/testfile";
// move the file
$finefs->rename($form, $to);

?>

Get a list of files

The getList() method can be used to search files matching an expression. It returns a list of informations, each one like the ones returned by getInfo().

// expression
$search = "public/data/*";
// search files
$list = $finefs->getList($search);

// print list
print_r($list);

?>

Output:

Array
(
    [public/data/testfile] => Array
        (
            [origin] => hostname
            [id] => 8ce7be3bee4c3f2fd55c79805a0c8004
            [date] => 2009-07-31T15:23:54+02:00
            [size] => 18
            [md5] => 9db708a207436fd6400aae2861194a49
        )

    [public/data/testfile-meta] => Array
        (
            [color] => blue
            [mimetype] => text/plain
            [origin] => hostname
            [id] => ffd55a4999401d90be5173c5f7048537
            [date] => 2009-07-31T15:00:46+02:00
            [size] => 18
            [md5] => 9db708a207436fd6400aae2861194a49
        )
)

Directories are returned with a special mimetype:

// expression
$search = "public/data";
// search files
$list = $finefs->getList($search);

// print list
print_r($list);

?>

Output:

Array
(
    [public/data] => Array
        (
            [mime] => inode/directory
        )
)

Error management

FineFS library's methods may raise some exceptions if an error is encountered. You should call them in a try...catch block. They can raise some IOExeption or ApplicationException, which are defined in the FineFS code (no need to include some other file).

<?php

require_once("/path/to/finefs/lib/php/class.FineFS.php");

try {
        $finefs = new FineFS();
        $finefs->...
} catch (IOException $ioe) {
        // IO error: unable to open a file
} catch (ApplicationException $ae) {
        // application error: bad configuration, no usable node, bad parameter
}

?>