org.astrogrid.acr.astrogrid
Interface Myspace

Deprecated. use Manager

@Deprecated
public interface Myspace

AR Service: A distributed file storage system.

Myspace is Astrogrid's prototype implementation of VOSpace.

Warning:

This component just provides access to Myspace files. The Manager component provides access to a wider range of filesystems - VOSpace, Myspace, plus FTP and some others.

Notes:

All resources in myspace are uniquely identified by a myspace resource identifier - which is an URI of form
ivo://Community-Id/User-Id#File-Path.
However, for convenience methods in this interface also accept an abridged form of reference - #File-Path - this is resolved relative to the currently logged-in user's homespace. The abridged form is more concise, and means hard-coded file references can be avoided if needed. It also provides a way to future-proof client code against the migration from myspace to vospace.

See Also:

Example of creating a file, Example of reading from a file, Example of writing to a file, NodeInformation, Myspace file browser component, Dialogue for selecting myspace files

Service Name

astrogrid.myspace

Method Summary

URI	copy(URI srcIvorn, URI newParentIvorn, String newName) Deprecated. make a copy of a resource
void	copyContentToURL(URI ivorn, URL destination) Deprecated. Copy the contents (data) of a resource out of myspace into a URL location.
void	copyURLToContent(URL src, URI ivorn) Deprecated. Copy the contents (data) of a URL location into a myspace resource
URI	createChildFile(URI parentFolder, String name) Deprecated. create a child file of the specified resource.
URI	createChildFolder(URI parentFolder, String name) Deprecated. create a child folder of the specified resource.
void	createFile(URI filename) Deprecated. create a new myspace file.
void	createFolder(URI foldername) Deprecated. create a new myspace folder.
void	delete(URI ivorn) Deprecated. delete a myspace resource.
boolean	exists(URI filename) Deprecated. test whether a myspace resource exists.
URI	getHome() Deprecated. Retrieve the identifier of the current user's home folder in myspace.
NodeInformation	getNodeInformation(URI filename) Deprecated. access metadata about a myspace resource.
URI	getParent(URI filename) Deprecated. retrieve the ID of the parent of a myspace resource.
URL	getReadContentURL(URI ivorn) Deprecated. Compute a URL which can then be read to access the contents (data) of a myspace resource.
URL	getWriteContentURL(URI ivorn) Deprecated. Compute a URL which can then be written to set the contents (i.e.
String[]	list(URI ivorn) Deprecated. list the names of the children (files and folders) of a myspace folder.
URI[]	listIvorns(URI ivorn) Deprecated. list the identifiers of the children ( files and folders) of a myspace folder.
NodeInformation[]	listNodeInformation(URI ivorn) Deprecated. list the node information objects for the children ( files and folders) of a myspace folder.
URI	move(URI srcIvorn, URI newParentIvorn, String newName) Deprecated. move a myspace resource.
String	read(URI ivorn) Deprecated. read the content of a myspace resource directly.
byte[]	readBinary(URI ivorn) Deprecated. read the binary content of a myspace resource directly.
void	refresh(URI ivorn) Deprecated. refresh the metadata held about a myspace resource with the server.
URI	rename(URI srcIvorn, String newName) Deprecated. rename a myspace resource.
void	transferCompleted(URI ivorn) Deprecated. Notify the filemanager server that the data for a filestore node has been changed.
void	write(URI ivorn, String content) Deprecated. Write data to a myspace resource.
void	writeBinary(URI ivorn, byte[] content) Deprecated. Write binary data to a myspace resource.

Method Detail

getHome

URI getHome()
            throws SecurityException,
                   ServiceException,
                   NotFoundException

Deprecated.

Retrieve the identifier of the current user's home folder in myspace. Each user has a single root folder. this method returns the name of it.

Returns:

uri of the home folder - typically has form ivo://Community-Id/User-Id#

Throws:

SecurityException - if authentication / authorization fails

ServiceException - if error occurs calling the service

NotFoundException - if there is no home folder associated with the user

exists

boolean exists(URI filename)
               throws ServiceException,
                      SecurityException,
                      InvalidArgumentException

Deprecated.

test whether a myspace resource exists.

Parameters:

filename - uri to check (full or abridged form)

Returns:

true if the resource exists

Throws:

ServiceException - if error occurs calling the service

SecurityException - if the user is not permitted to inspect this ivorn (e.g. it is private to another user)

InvalidArgumentException

getNodeInformation

NodeInformation getNodeInformation(URI filename)
                                   throws ServiceException,
                                          NotFoundException,
                                          SecurityException,
                                          InvalidArgumentException

Deprecated.

access metadata about a myspace resource.

Warning:

At the moment, this is a costly operation

Parameters:

filename - resource to investigate

Returns:

a beanful of information

Throws:

ServiceException - if error occurs calling the service

NotFoundException - if this resource does not exist

SecurityException - it the user is not permitted to inspect this resource

InvalidArgumentException - if the ivorn is malformed.

XMLRPC

will return a map. see NodeInformation for available keys.

createFile

void createFile(URI filename)
                throws ServiceException,
                       SecurityException,
                       InvalidArgumentException

Deprecated.

create a new myspace file. Any parent folders that are missing will be created too.

Python Example

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
ms = ar.astrogrid.myspace
 #call this function
file = '#votable/a-new-file.vot'
if not (ms.exists(file)):
   ms.createFile(file)

Java Example

import org.astrogrid.acr.*;
import java.net.URI;
import org.astrogrid.acr.astrogrid.Myspace;
import org.astrogrid.acr.builtin.ACR
Finder f = new Finder();
ACR acr = f.find();
Myspace ms = (Myspace)acr.getService(Myspace.class);
URI file =new URI("#votable/a-new-file.vot");
if (! ms.exists(file)) {
   ms.createFile(file)
}

Parameters:

filename - the resource to create.

Throws:

ServiceException - if error occurs calling the service

SecurityException - if the user is not permitted to create this resource.

InvalidArgumentException - if this resource already exists,, or one of the parent resources already exists and is not a folder

createFolder

void createFolder(URI foldername)
                  throws ServiceException,
                         SecurityException,
                         InvalidArgumentException

Deprecated.

create a new myspace folder. Any parent folders that are missing will be created too.

Parameters:

foldername - the resource to create.

Throws:

ServiceException - if error occurs calling the service

SecurityException - if the user is not permitted to create this resource.

InvalidArgumentException - if this resource already exists, or one of the parent resources already exists and is not a folder

createChildFolder

URI createChildFolder(URI parentFolder,
                      String name)
                      throws NotFoundException,
                             ServiceException,
                             SecurityException,
                             InvalidArgumentException,
                             NotApplicableException

Deprecated.

create a child folder of the specified resource.

Parameters:

parentFolder - parent of the new resource (must be a folder)

name - name of the new folder

Returns:

the ivorn of the new folder

Throws:

NotFoundException - if the parent does not exist.

ServiceException - if error occurs calling the service

SecurityException - if the user is not permitted to create folders here

InvalidArgumentException - if a child file or folder with this name already exists,

NotApplicableException - if the parent is not a folder

createChildFile

URI createChildFile(URI parentFolder,
                    String name)
                    throws NotFoundException,
                           ServiceException,
                           SecurityException,
                           InvalidArgumentException,
                           NotApplicableException

Deprecated.

create a child file of the specified resource.

Parameters:

parentFolder - parent of the new resource (must be a folder)

name - name of the new file

Returns:

the ivorn of the new file

Throws:

NotFoundException - if the parent does not exist

ServiceException - if error occurs calling the service

SecurityException - if the user is not permitted to create files here

InvalidArgumentException - if a child file or folder with this name already exists

NotApplicableException - if the parent is not a folder

getParent

URI getParent(URI filename)
              throws NotFoundException,
                     InvalidArgumentException,
                     ServiceException,
                     SecurityException

Deprecated.

retrieve the ID of the parent of a myspace resource.

Parameters:

filename - uri of the resource to find parent for

Returns:

uri of the parent

Throws:

NotFoundException - if ivorn does not exist

InvalidArgumentException - if ivorn has no parent - i.e. is the home directory.

ServiceException - if a erorr occurs calling the service

SecurityException - if the user is not permitted to inspect this resource

list

String[] list(URI ivorn)
              throws ServiceException,
                     SecurityException,
                     NotFoundException,
                     InvalidArgumentException

Deprecated.

list the names of the children (files and folders) of a myspace folder.

Parameters:

ivorn - uri of the folder to inspect

Returns:

an array of the names of the contents.

Throws:

ServiceException - if an error occurs calling the service

SecurityException - if the user is not permitted to inspect this resource

NotFoundException - if ivorn does not exist

InvalidArgumentException - if ivorn is not a folder

listIvorns

URI[] listIvorns(URI ivorn)
                 throws ServiceException,
                        SecurityException,
                        NotFoundException,
                        InvalidArgumentException

Deprecated.

list the identifiers of the children ( files and folders) of a myspace folder.

Parameters:

ivorn - uri of the folder to inspect

Returns:

an array of the ivorns of the contents.

Throws:

ServiceException - if an error occurs calling the service

SecurityException - if the user is not permitted to inspect this resource

NotFoundException - if ivorn does not exist

InvalidArgumentException - if ivorn is not a folder

listNodeInformation

NodeInformation[] listNodeInformation(URI ivorn)
                                      throws ServiceException,
                                             SecurityException,
                                             NotFoundException,
                                             InvalidArgumentException

Deprecated.

list the node information objects for the children ( files and folders) of a myspace folder.

Warning:

Expensive operation at present.

Parameters:

ivorn - uri of the folder to inspect

Returns:

an array of the node information objects.

Throws:

ServiceException - if an error occurs calling the service

SecurityException - if the user is not permitted to inspect this resource

NotFoundException - if ivorn does not exist

InvalidArgumentException - if ivorn is not a folder

refresh

void refresh(URI ivorn)
             throws SecurityException,
                    ServiceException,
                    NotFoundException,
                    InvalidArgumentException

Deprecated.

refresh the metadata held about a myspace resource with the server.

Note:

For performance, metadata about myspace resources is used in a LRU cache. This method forces the ACR to re-query the myspace server about this resource.

Parameters:

ivorn - resource to refresh

Throws:

SecurityException - if the user is not permitted to inspect this resource

ServiceException - if an error occurs calling the service

NotFoundException - if the resource does not exist.

InvalidArgumentException

delete

void delete(URI ivorn)
            throws NotFoundException,
                   SecurityException,
                   ServiceException,
                   InvalidArgumentException

Deprecated.

delete a myspace resource.

Parameters:

ivorn - uri of the resource to delete

Throws:

NotFoundException - if the resource does not exist

SecurityException - if the user is not permitted to delete this resource

ServiceException - if an error occurs calling the service

InvalidArgumentException - if the resouce is a folder that contains further resources - delete these first.

rename

URI rename(URI srcIvorn,
           String newName)
           throws NotFoundException,
                  SecurityException,
                  ServiceException,
                  InvalidArgumentException

Deprecated.

rename a myspace resource.

Parameters:

srcIvorn - uri of the resource to renam

newName - new name for this resource

Returns:

uri pointing to the renamed resource (original uri may now be invalid)

Throws:

NotFoundException - if the resource does not exist

SecurityException - if the user is not permitted to rename this resource

ServiceException - if an error occurs calling the service

InvalidArgumentException - if the newName is already taken by anotherh resource in this folder.

move

URI move(URI srcIvorn,
         URI newParentIvorn,
         String newName)
         throws NotFoundException,
                InvalidArgumentException,
                SecurityException,
                ServiceException,
                NotApplicableException

Deprecated.

move a myspace resource.

Parameters:

srcIvorn - ivorn of the resource to move

newParentIvorn - ivorn of the new parent

newName - new name for this resource.

Returns:

uri pointing to the moved resouce (original uri will now be invalid)

Throws:

NotFoundException - if either the source or new folder resources cannot be found

InvalidArgumentException - if a resource with name =newName= already exists in the new folder

SecurityException - if the user is not permitted to move this resource

ServiceException - if an error occurs calling the service.

NotApplicableException - if the new parent is not a folder

copy

URI copy(URI srcIvorn,
         URI newParentIvorn,
         String newName)
         throws NotFoundException,
                InvalidArgumentException,
                ServiceException,
                SecurityException

Deprecated.

make a copy of a resource

Parameters:

srcIvorn - uri of the resource to copy

newParentIvorn - uri of the folder to copy to

newName - name to copy to

Returns:

uri pointing to the resource copy

Throws:

NotFoundException - if the original resource or new parent do not exist

InvalidArgumentException - if the new parent is not a folder, or already contains a resource called 'newName'

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to copy this resource

read

String read(URI ivorn)
            throws NotFoundException,
                   InvalidArgumentException,
                   ServiceException,
                   SecurityException,
                   NotApplicableException

Deprecated.

read the content of a myspace resource directly.

Warnings:

not a good idea for large files. in this case use Myspace.copyContentToURL(URI, URL) or Myspace.getReadContentURL(URI)

Parameters:

ivorn - resource to read

Returns:

content of this resource (as a string)

Throws:

NotFoundException - if this resource does not exist.

InvalidArgumentException - if this resource is malformed

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to access this resource

NotApplicableException - if this resource has no data - e.g. it is a folder

write

void write(URI ivorn,
           String content)
           throws InvalidArgumentException,
                  ServiceException,
                  SecurityException,
                  NotApplicableException

Deprecated.

Write data to a myspace resource.

Warnings:

not a good idea for large files. In this case use Myspace.copyURLToContent(URL, URI)

Parameters:

ivorn - resource to write to

content - the data to write

Throws:

InvalidArgumentException - is the resource is malformed

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to access this resource

NotApplicableException - if this resource cannot contain data - e.g. it is a folder

readBinary

byte[] readBinary(URI ivorn)
                  throws NotFoundException,
                         InvalidArgumentException,
                         ServiceException,
                         SecurityException,
                         NotApplicableException

Deprecated.

read the binary content of a myspace resource directly.

Warnings:

not a good idea for large files. in this case use Myspace.copyContentToURL(URI, URL) or Myspace.getReadContentURL(URI)

Parameters:

ivorn - resource to read

Returns:

byte array of the contents of this resource

Throws:

NotFoundException - if this resource does not exist.

InvalidArgumentException - if this resource is malformed

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to access this resource

NotApplicableException - if this resource cannot contain data - e.g. it is a folder

writeBinary

void writeBinary(URI ivorn,
                 byte[] content)
                 throws InvalidArgumentException,
                        ServiceException,
                        SecurityException,
                        NotApplicableException

Deprecated.

Write binary data to a myspace resource.

Warnings:

not a good idea for large files. In this case use Myspace.copyURLToContent(URL, URI)

Parameters:

ivorn - resource to write to

content - the data to write

Throws:

InvalidArgumentException - is the resource is malformed

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to access this resource * @throws NotApplicableException if this resource cannot contain data - e.g. it is a folder

NotApplicableException

getReadContentURL

URL getReadContentURL(URI ivorn)
                      throws NotFoundException,
                             InvalidArgumentException,
                             ServiceException,
                             SecurityException,
                             NotApplicableException

Deprecated.

Compute a URL which can then be read to access the contents (data) of a myspace resource.

Python Example

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
from urllib2 import urlopen
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
ms = ar.astrogrid.myspace
 #get the data url for a myspace file
msfile = '#results/datafile.vot'
dataUrl = ms.getReadContentURL(msfile)
 # read from the data url
urlFile = urlopen(dataUrl)
print urlFile
 

Java Example

import org.astrogrid.acr.*;
import java.net.URI;
import org.astrogrid.acr.astrogrid.Myspace;
import org.astrogrid.acr.builtin.ACR
Finder f = new Finder();
ACR acr = f.find();
Myspace ms = (Myspace)acr.getService(Myspace.class);
URI file =new URI("#results/datafile.vot");
URL dataUrl = ms.getReadContentURL(file);
InputStream is = dataUrl.openStream();
  // read in data..

Parameters:

ivorn - resource to read

Returns:

a url from which the contents of the resource can be read

Throws:

NotFoundException - if the resource does not exist

InvalidArgumentException - if the resource is not a file

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to read the contents of this resource

NotApplicableException - if this resource cannot contain data - e.g. it is a folder

getWriteContentURL

URL getWriteContentURL(URI ivorn)
                       throws NotFoundException,
                              InvalidArgumentException,
                              ServiceException,
                              SecurityException,
                              NotApplicableException

Deprecated.

Compute a URL which can then be written to set the contents (i.e. data) of a myspace resource. For the current filestore impleentation the result returned is a http:// url, to which data should be PUT (not POST).

Note:

After the data has been written to the filestore, the filemanager needs to be notified that the data for this node has changed - by calling Myspace.transferCompleted(java.net.URI)

Here's how to PUT and then notify of completion:

Java Example

import org.astrogrid.acr.*;
import java.net.*;
import org.astrogrid.acr.astrogrid.Myspace;
import org.astrogrid.acr.builtin.ACR
Finder f = new Finder();
ACR acr = f.find();
Myspace ms = (Myspace)acr.getService(Myspace.class);
URI file =new URI("#results/datafile.vot");
 //get the output url
URL url = ms.getWriteContentURL(file); 
HttpURLConnection conn  = (HttpURLConnection) url.openConnection() ;
conn.setDoOutput(true) ;
conn.setRequestMethod("PUT");
  // connect
conn.connect();
OutputStream os = conn.getOutputStream(); 
 //write the data
 ...
  //close
os.close();
 // important - the URL connection class won't tranfer data unless you ask for a response - this is a nasty gotcha, not clear from the javadocs.
conn.getResponseCode() // necessary to force the whole thing to happen
ms.transferCompleted(file); // tell the filemanager that the content for this resource has changed.

Parameters:

ivorn - resource to write to

See Also:

Myspace.transferCompleted(java.net.URI)

Returns:

a url to which the contents of the resource can be written

Throws:

NotFoundException - if the resource does not exist

InvalidArgumentException - if the resource is not a file

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to write the contents of this resource

NotApplicableException - if this resource cannot contain data - e.g. it is a folder

transferCompleted

void transferCompleted(URI ivorn)
                       throws NotFoundException,
                              InvalidArgumentException,
                              ServiceException,
                              SecurityException,
                              NotApplicableException

Deprecated.

Notify the filemanager server that the data for a filestore node has been changed. This method must be called after storing data in a myspace file via the URL returned by Myspace.getWriteContentURL(java.net.URI). There's no need to call this method when storing data using any other method

Parameters:

ivorn - the myspace resource just written to

See Also:

Myspace.getWriteContentURL(java.net.URI)

Throws:

NotFoundException - if the resource does not exist

InvalidArgumentException - if the resource is not writable

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to access this resource

NotApplicableException - if this resouce cannot contain data - e.g. it is a folder

copyContentToURL

void copyContentToURL(URI ivorn,
                      URL destination)
                      throws NotFoundException,
                             InvalidArgumentException,
                             ServiceException,
                             SecurityException,
                             NotApplicableException

Deprecated.

Copy the contents (data) of a resource out of myspace into a URL location.

Parameters:

ivorn - the myspace resource to write out

destination - a writable URL - file:/, http:/ or ftp:/ protocol

Throws:

NotFoundException - if the myspace resource does not exist

InvalidArgumentException - if the destination is not writable

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to read the contents of this resource

NotApplicableException - if this resource cannot contain data - e.g. it is a folder *

copyURLToContent

void copyURLToContent(URL src,
                      URI ivorn)
                      throws NotFoundException,
                             InvalidArgumentException,
                             ServiceException,
                             SecurityException,
                             NotApplicableException

Deprecated.

Copy the contents (data) of a URL location into a myspace resource

Parameters:

src - url to read data from - file:/, http:/ or ftp:/ protocol.

ivorn - the myspace resource to store the data in.

Throws:

NotFoundException - if the folder containing the new myspace resource does not exist

InvalidArgumentException - if the src is not readable

ServiceException - if an error occurs while calling the service

SecurityException - if the user is not permitted to write the contents of this resource

NotApplicableException - if this resource cannot contain data - e.g. it is a folder *