By Abel Lin
November 7, 2007
Part 1 of this series introduced you to a set of Perl-based tools that are part of a data management toolkit that we use at SundayMorningRides.com. That article primarily covered basic file/data manipulation: listing, I/O, etc. A large part of data management, of course, is sharing data. The examples in this article add to the functionality of the data management toolkit presented in part 1 by creating tools that allow you to use the AOL Open Xdrive (Xdrive) API as a data-sharing platform.
I will assume that you have read the first article and already know how to authenticate to Xdrive, so I will dive right in. The following example presents a scenario in which a grantor would like to share a folder with a grantee. I should also mention that recently AOL released version 1.2 of the AOL Xdrive Data Service Platform (XDSP) JavaScript Object Notation (JSON) API, which includes several new features—notably, expanded authentication, including using the AOL Open Authentication (OpenAuth) API.
Set (and Verify) Permissions on a Folder
To set permissions on a folder, the example here uses the aptly named share.grantpermission method. You might also notice that this example directly creates the data parameter with JSON notation, rather than first encoding it in Perl object notation, as in the first article. Here, you are setting read and write permissions. There are several other permission types (all are Boolean), including:
hasCreatehasModifyhasDeletehasShareisPublic
You set the folder you would like to share in the toGrant input and set to whom you would like to share (the grantee), and the grantee's input. In the case of the grantee, you can set their ID or their e-mail. If you use their e-mail, the ContactObject will be added to the user's address book. If that e-mail is already in the address book, the ContactObject that matches will be used. Note that in this example, Perl syntax requires that you use the use the backslash character (\) for the @.
There is also an optional MailMessageObject with which you can create a custom e-mail notification to send to the grantee.
#!/usr/bin/perl
use LWP::UserAgent;
use JSON;
use Data::Dumper;
open(FILE, ".jsessionid"); @raw=<FILE>; close(FILE);
$JSESSIONID = $raw[0];
chomp $JSESSIONID;
my $ua = LWP::UserAgent->new;
my $json = JSON->new(pretty => 1, delimiter => 0);
(my $json_req = <<"JSON");
{
"permissions": {
"type":"SharePermissionObject",
"hasRead":"true",
"hasWrite":"true"
},
"toGrant":[{
"type":"FileObject",
"id":"xdr:XFS-1592274213"
}],
"grantees":[{
"type":"ContactObject","email":"username\@aim.com"
}]
}
JSON
my $url = "http://plus.xdrive.com/json/v1.2/share.grantpermission;jsessionid=
$JSESSIONID?data=$json_req";
my $response = $ua->post($url);
$content = $response->content;
$obj = $json->jsonToObj($content);
print Dumper $obj;
Note that if the grantee already has permission to access the folder, the new permission settings will overwrite the old settings. So, for example, even if the grantee already has read, write, and create permissions, after executing this example, the grantee will only have read and write permissions. Also notice the share.revokepermission method, which does exactly as the name implies.
After setting permissions, it is always good to verify that permissions were set properly. To do this, you can use the share.listoutboundshares method.
#!/usr/bin/perl
use LWP::UserAgent;
use JSON;
use Data::Dumper;
open(FILE, ".jsessionid"); @raw=<FILE>; close(FILE);
$JSESSIONID = $raw[0];
chomp $JSESSIONID;
my $ua = LWP::UserAgent->new;
my $json = JSON->new(pretty => 1, delimiter => 0);
(my $json_req = <<"JSON");
{
"srcFile":{
"type":"FileObject",
"id":"xdr:XFS-1592274213"
}
}
JSON
my $url = "http://plus.xdrive.com/json/v1.2/share.listoutboundshares;
jsessionid=$JSESSIONID?data=$json_req";
my $response = $ua->post($url);
$content = $response->content;
$obj = $json->jsonToObj($content);
print Dumper $obj;
Use a Shared Folder
Now, shift gears and continue the scenario as the grantee. First, you will check for folders that have been shared with you. As you might have already guessed, this is accomplished using the share.listinboundshares method.
#!/usr/bin/perl use LWP::UserAgent; use JSON; use Data::Dumper; open(FILE, ".jsessionid"); @raw=<FILE>; close(FILE); $JSESSIONID = $raw[0]; chomp $JSESSIONID; my $ua = LWP::UserAgent->new; my $json = JSON->new(pretty => 1, delimiter => 0); my $url = "http://plus.xdrive.com/json/v1.2/share.listinboundshares;
jsessionid=$JSESSIONID"; my $response = $ua->post($url); $content = $response->content; $obj = $json->jsonToObj($content); print Dumper $obj;
You will want to note the ID of the SharePermissionObject. To start using this shared folder, you will want to map this shared folder to your account. To do this, use the share.mapfolder method.
#!/usr/bin/perl
use LWP::UserAgent;
use JSON;
use Data::Dumper;
open(FILE, ".jsessionid"); @raw=<FILE>; close(FILE);
$JSESSIONID = $raw[0];
chomp $JSESSIONID;
my $ua = LWP::UserAgent->new;
my $json = JSON->new(pretty => 1, delimiter => 0);
(my $json_req = <<"JSON");
{
"toMap":{
"type":"SharePermissionObject",
"id":"xdr:3771497"
}
}
JSON
my $url = "http://plus.xdrive.com/json/v1.2/share.mapfolder;
jsessionid=$JSESSIONID?data=$json_req";
my $response = $ua->post($url);
$content = $response->content;
$obj = $json->jsonToObj($content);
print Dumper $obj;
There is an optional destFolder input (of data type FileObject) that you can use to rename the folder and/or to identify the parent folder of the mapped shared folder you want to use. If not set, the user's "root" folder is assumed to be the target and the original folder's name will be used. You can now interact with this folder as if it were your own (with perhaps limited permissions).
When you are done with a folder, you can unmap it using the share.unmapfolder method. Note that the input requires a FileObject ID (for example, using the file.getlisting method) and not the SharePermissionObject ID that was used to map the folder.
#!/usr/bin/perl
use LWP::UserAgent;
use JSON;
use Data::Dumper;
open(FILE, ".jsessionid"); @raw=<FILE>; close(FILE);
$JSESSIONID = $raw[0];
chomp $JSESSIONID;
my $ua = LWP::UserAgent->new;
my $json = JSON->new(pretty => 1, delimiter => 0);
(my $json_req = <<"JSON");
{
"toUnmap":[{
"type":"FileObject","id":"xdr:XFS-1705930640"
}]
}
JSON
my $url = "http://plus.xdrive.com/json/v1.2/share.unmapfolder;
jsessionid=$JSESSIONID?data=$json_req";
my $response = $ua->post($url);
$content = $response->content;
$obj = $json->jsonToObj($content);
print Dumper $obj;
Summary
Like the data management tools I discussed in part 1 of this article, you can easily add a few arguments to create a set of XCommands that mirror the UNIX command line (yes, that is actually a mixture of two UNIX commands, but it works!).
% Xchown +rw username@aim.com Xdrive_folder_id
Xdrive is a great resource for collaborative data management. At SundayMorningRides.com, we use Xdrive not only for sharing data between our developers, but also with our external collaborators. We simply set up a shared folder, send a quick note using AOL Instant Messenger (AIM), and we are off and running. There's no need to mess with an FTP site or even e-mail attachments.
Although our team primarily uses Xdrive as a set of command-line tools, it is by no means limited to that type of client interface. The folks at BlueString have developed a rich, interactive web-based interface for Xdrive for preserving, mixing, and sharing personal digital media files.