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 *


Copyright © 2002-2010 AstroGrid. All Rights Reserved.