Mdclient - Perl API to AMGA metadata service
The Mdclient.pm Perl module contains the Mdclient class which supports X509 certificate, grid proxy or password based authentication to a AMGA server over SSL as well as operation without SSL.
To use the Mdclient class include a
use Mdclient;
statement. A script mdtest with usage examples for most methods is shipped with the module.
Mdclient uses the Net::SSLeay and IO::Socket::INET modules as the APIs to openssl and sockets. Mdclient was tested with Net::SSLeay version 1.26 patched to support SSL session caching. Versions >1.26 are realeased with SSL session caching functionality, so that no patching is needed.
new - constructor
$cl = Mdclient->new( Host => <host>,
Port => <port>,
Login => <user name>,
[Password => <password>,]
[Debug => 1,]
);
requireSSL - use SSL
$cl->requireSSL(<key file path>, <cert file path>); In case of grid proxy based authentication both arguments of requireSSL must point to the grid proxy file.
addAttr - add attributes to collection
$code = $cl->addAttr(<path>, %attr); %attr hash: its keys are attribute names, its values are attribute values.
addEntries - add entries
$code = $cl->addEntries(<list of entry paths>);
addEntry - add entry with attributes
$code = $cl->addEntry(<entry path>[, %attr]); The keys of the optional %attr hash are attribute names and its values are attribute values.
cd - change working directory
$code = $cl->cd(<dir path>);
clearAttr - clear attributes
$code = $cl->clearAttr(<entry path>, <attribute name>);
commit - commit upload
$code = $cl->commit;
createDir - create directory
$code = $cl->createDir(<directory path>[, @keys]); @keys is an optional list of keywords)
dir - list directory
$code = $cl->dir([<directory path>]);
disconnect - disconnect from AMGA server.
$cl->disconnect(<mode>); If <mode> is 1 saves current SSL session. If <mode> is 2 calls exit method to ensure destruction of session by server. If <mode> is not set session will not be saved and exit will not be called (useful, when server does not allow sessions or exit was called before).
eot - used with the iterator methods getEntry, getSelectAttrEntry and fetchRow. Returns true when no entries/rows are left.
while($cl->eot) {..}
fetchRow - used to fetch next line of output from AMGA server (streaming).
$line = $cl->fetchRow; $line will contain next line of output from AMGA server.
find - list entry names matching path pattern and fulfilling the query with their attributes
$code = $cl->find(<path pattern>, <query>);
getAttr - get attributes of entries
$code = $cl->getAttr(<path pattern>, @attr); @attr is a list of attribute names.
getEntry - get one entry requested by getAttr method
($entry, @values) = $cl->getEntry; @values list: contains values corresponding to @attr from getAttr method.
getErrorMsg - get last error message
$msg = $cl->getErrorMsg;
getSelectAttrEntry - retrieve one entry requested by selectAttr method.
@values = $cl->getSelectAttrEntry; @values list: contains values corresponding to @attr from selectAttr method.
listAttr - list attributes
($code, %res) = $cl->listAttr(<directory path>); %res hash: the keys are attribute names, the values are attribute types.
put - inserts a new entry during upload. Errors are returned by the call immediately, OK is delayed until upload is commited.
$code = $cl->put(<entry>, @values); <entry> is the name of the entry to be inserted, @values is a list of attribute values.
pwd - print working directory
($code, $directory) = $cl->pwd; $directory will contain the working directory.
removeAttr - remove attribute from collection
$code = $cl->removeAttr(<directory path>, <attribute name>);
rmdir - remove directory
$code = $cl->rmdir(<directory path>);
rm - remove entries
$code = $cl->rm(<pattern string>[, <option>]); <option> is optional and being set to 'r' it makes rm recursively.
schemaCreate - create collection with attributes
$code = $cl->schemaCreate(<directory path>[, %attr]); The keys of the optional %attr hash are attribute names, the values are attribute types.
selectAttr - select attributes from several collections based on a condition doing an inner join on the collections based on a join condition
$code = $cl->selectAttr(<query>, @attr); @attr is a list of attribute names.
setAttr - set attributes
$code = $cl->setAttr(<entry path>, %attr); %attr hash: the keys are attribute names, the values are attribute values.
stat - return information on a given entry or directory. Alias for ls -Pmgl
$code = $cl->stat(<path>);
updateAttr - update attributes
$code = $cl->updateAttr(<path pattern>, <query>, %attr); %attr hash: the keys are attribute names, the values are attribute values.
upload - upload entries in transaction
$code = $cl->upload(<directory path>[, @attr]); @attr is a list of attribute names.
put - insert a new entry during upload
$code = $cl->put(<entry name>, @values); @values is a list of attribute values;
Most methods from section above (excepted createDir and schemaCreate) may also be used with a File Catalog.
mkdir - create directory for file entries
$code = $cl->mkdir(<directory path>[, @keys]); @keys is an optional list of keywords
ls - list files in a directory
$code = $cl->ls([<path>[, <options>]]); Both arguments are optional. If given, <options> is a string of options, e.g. "lmP".
lfn_lookup - Look up LFN's for a list of given GUID's
$code = $cl->lfn_lookup(@guids); @guids is a list of GUIDs.
replica_add - adds a replica at SURL to the replicas of the file with the given GUID
$code = $cl->replica_add(<GUID>, <SURL>);
replica_get - list the SURL replicas of files given as GUIDs or LFNs
$code = $cl->replica_get(<option>, @list); If <option> is "l" @list is assumed to contain LFNs, else @list is assumed to contain GUIDs.
replica_list - lists the sites with replicas of files given as GUIDs or LFNs
$code = $cl->replica_list(<option>, @list); If <option> is "l" @list is assumed to contain LFNs, else @list is assumed to contain GUIDs.
replica_register - Registers a site to a central catalog that has a certain file
$code = $cl->replica_register(<GUID>, <site>);
replica_remove - removes a replica for a GUID
$code = $cl->replica_remove(<replica>[, <GUID>]);
replica_unregister - unregisters replica on a site at a central catalog
$code = $cl->replica_unregister(<GUID>, <site>);
site_add - registers a site
$code = $cl->site_add(<site>, <host>, <port>); <site> is a site name, <host> a hostname, <port> the port number.
site_get_property - gets one or more configuration properties of a site
$code = $cl->site_get_property(<site>, @property_names); @property_names is a list of property names.
site_list - lists all sites and their ID
$code = $cl->site_list;
site_list_properties - lists all configuration properties of a site
$code = $cl->site_list_properties(<site>);
site_remove - removes a site
$code = $cl->site_remove(<site>); <site> is a site name, represented as a string.
site_set_property - updates one or more configuration properties of a site
$code = $cl->site_set_property(<site>, %properties); The %properties hash keys are property names and its values are property values.
rep_allow - grants to <group> the right to replicate <directory> and all its subdirectories
$code = $cl->rep_allow(<directory>, <group>);
rep_disallow - remove from <group> the right to replicate <directory> and all its subdirectories
$code = $cl->rep_disallow(<directory>, <group>);
rep_list_mounts - lists all mount points
$code = $cl->rep_list_mounts;
rep_list_subscribers - show the current subscribers and their subscriptions
$code = $cl->rep_list_subscribers;
rep_mount - mounts a directory from the server running at the given address
$code = $cl->rep_mount(<master>, <remoteDirectory>, <permissions>); <permissions> - is a string of corresponding letters (no leading '-')
rep_mount_users - replicate user and groups information from a remote node
$code = $cl->rep_mount_users(<master>);
rep_show_permissions - show the replication rights for all directories
$code = $cl->rep_show_permissions;
rep_start_receive - connects to the master and starts listening for the logs of all mount points from this master
$code = $cl->rep_start_receive(<master>);
rep_start_receive - stops listening for the logs of all mount points from this master
$code = $cl->rep_stop_receive(<master>);
rep_umount - unmounts a replication point, local data is deleted
$code = $cl->rep_umount(<remoteDirectory>);
rep_umount_users - drops the user and group information that was being replicated from a master
$code = $cl->rep_umount_users;
mdtest