Module file
Back to master index
Module fileVersion:1.0.0
Package:org.astrogrid.acr.file
Access to filesystems
Service Points
file.info
file.manager
file.name
file.systems
4 service points
Contribution to framework.acrServices
<acrService id="manager" interface="Manager" />
<acrService id="systems" interface="Systems" />
<acrService id="info" interface="Info" />
<acrService id="name" interface="Name" />
Contribution to framework.descriptors
<acr-module description="Access to Filesystems" name="file" >
  • <component description="Inspect metadata about URI file references. This module provides methods to check whether a URI reference exists, and whether is a file, a folder, is hidden, readable or writable. For files, the size, content-type and attributes may also be accessed.<dl> <dt>See:</dt><dd> Manager, Name, </dd></dl>" interface-class="org.astrogrid.acr.file.Info" name="info" >
    • <method description="Determine if a URI exists." name="exists" >
      • <return description="<tt>true</tt> if this URI exists, else <tt>false</tt>" type="boolean" uitype="boolean" />
      • <param description="the resource to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Test whether a URI exists and is a file.<dl> <dt>See:</dt><dd> #exists(URI), </dd></dl>" name="isFile" >
      • <return description="<tt>true</tt> if this is an existing file." type="boolean" uitype="boolean" />
      • <param description="the resource to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Tests whether a URI exists and is a folder.<dl> <dt>See:</dt><dd> #exists(URI), </dd></dl>" name="isFolder" >
      • <return description="<tt>true</tt> if this is an existing folder." type="boolean" uitype="boolean" />
      • <param description="the resource to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Determine if a URI exists and is hidden. If the resource does not exist, will return <tt>false</tt>" name="isHidden" >
      • <return description="<tt>true</tt> if this resource is hidden" type="boolean" uitype="boolean" />
      • <param description="the resource to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Determine if a URI exists and is readable." name="isReadable" >
      • <return description="<tt>true</tt> if this resource is readable" type="boolean" uitype="boolean" />
      • <param description="the resurce to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Determine if a URI is writable. If the resource does not yet exist, tests whether this resource could be created and written to." name="isWritable" >
      • <return description="<tt>true</tt> if this resource is writable." type="boolean" uitype="boolean" />
      • <param description="the resource to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Determine the last-modified timestamp of a resource." name="getLastModifiedTime" >
      • <return description="The last-modified timestamp. This represents the number milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT." type="long" uitype="long" />
      • <param description="the resource to inspect" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Inspect the attributes of this resource. Returns a dictionary of attributes. The particular entries in the dictionary will vary according to the kind of filesystem the resource belongs to. Dictionary keys will be strings, as most commonly will be the associated values.<dl> <dt>Note:</dt><dd> For a Myspace file, two attributes which will always be present are : <dl> <dt><tt>ContentURL</tt></dt> <dd>A URL (typically HTTP or FTP) from which the contents of this file can be directly read</dd> <dt><tt>ContentMethod</tt></dt> <dd>The method (for example GET) to use to access the <tt>ContentURL</tt></dd> </dl></dd></dl>" name="getAttributes" >
      • <return description="read-only map of this resource's attributes." type="java.util.Map" uitype="Map" />
      • <param description="the resource to inspect" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Determines the size of a file, in bytes." name="getSize" >
      • <return description="the size of the file, in bytes" type="long" uitype="long" />
      • <param description="the resource to inspect." name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Determine the content type of a file. Note that content type <i>may</i> be deduced by file-suffix - so results might differ from actual contents, especially for empty / non-existent files." name="getContentType" >
      • <return description="the content type of the file, or null if no type. Some typical values are: <tt>image/jpeg</tt>, <tt>text/plain</tt>, <tt>application/xml</tt>, <tt>application/x-votable+xml</tt>" type="java.lang.String" uitype="String" />
      • <param description="the file to test" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    </component>
  • <component description="Read, Write, and Navigate Filesystems.<dl> <dt>See:</dt><dd> Name, Info, Systems, </dd></dl>" interface-class="org.astrogrid.acr.file.Manager" name="manager" >
    • <method description="Create a file, if it does not exist. Also creates any ancestor folders which do not exist. This method does nothing if the file already exists and is a file." name="createFile" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the filepath to create" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Create a folder, if it does not exist. Also creates any ancestor folders which do not exist. Does nothing if the folder already exists." name="createFolder" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the folderpath to create" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Resynchronize the information about a file with the remote filesystem. May be necessary in cases when another client is writing to this file" name="refresh" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Delete a file and all it's descendants. Does nothing if this file does not exist." name="delete" >
      • <return description="true if the file was deleted." type="boolean" uitype="boolean" />
      • <param description="filepath to delete" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="List the names of the children of a folder." name="listChildren" >
      • <return description="An array containing the names of the children of this folder. The array is unordered. If the file does not have any children, a zero-length array is returned. This method never returns null." type="java.lang.String[]" uitype="String[]" />
      • <param description="the folder to list" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="List the URI of the children of a folder." name="listChildUris" >
      • <return description="An array containing the URIs of the children of this folder. The array is unordered. If the file does not have any children, a zero-length array is returned. This method never returns null." type="java.net.URI[]" uitype="URI[]" />
      • <param description="the folder to list" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Read the contents of a file." name="read" >
      • <return description="the contents of the file. An empty file will return an empty string, never NULL" type="java.lang.String" uitype="String" />
      • <param description="the file to read from" name="src" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Write to a file." name="write" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the file to write to" name="dest" type="java.net.URI" uitype="URI" />
      • <param description="the contents to write to the file." name="content" type="java.lang.String" uitype="String" />
      </method>
    • <method description="Read the contents of a file as binary data." name="readBinary" >
      • <return description="the contents of the file. Never NULL - an empty file will produce a zero-length array." type="byte[]" uitype="byte[]" />
      • <param description="the file to read from" name="src" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Write binary data to a file." name="writeBinary" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the file to write to" name="dest" type="java.net.URI" uitype="URI" />
      • <param description="the contents to write to the file." name="content" type="byte[]" uitype="byte[]" />
      </method>
    • <method description="Append to a file." name="append" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the file to write to" name="dest" type="java.net.URI" uitype="URI" />
      • <param description="the contents to append to the file." name="content" type="java.lang.String" uitype="String" />
      </method>
    • <method description="Append binary data to a file." name="appendBinary" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the file to write to" name="dest" type="java.net.URI" uitype="URI" />
      • <param description="the contents to append to the file." name="content" type="byte[]" uitype="byte[]" />
      </method>
    • <method description="Copy a file, and all it's descendants, to another location." name="copy" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the source file / folder" name="src" type="java.net.URI" uitype="URI" />
      • <param description="the destination to copy to. The destination may be on a different filesystem to <tt>src</tt>" name="dest" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Move a file (and all it's descendants) to another location." name="move" >
      • <return description="" type="java.lang.Void" uitype="void" />
      • <param description="the file to move" name="src" type="java.net.URI" uitype="URI" />
      • <param description="the destination to move to. This may be on a different filesystem to <tt>src</tt>" name="dest" type="java.net.URI" uitype="URI" />
      </method>
    </component>
  • <component description="Construct and manipulate URI file references. For two URI references (<tt>u1</tt>,<tt>u2</tt>) to be equal, the following must be true: <pre> getRoot(u1) == getRoot(u2) && getPath(u1) == getRoot(u2)</pre><dl> <dt>See:</dt><dd> Manager, Info, </dd></dl>" interface-class="org.astrogrid.acr.file.Name" name="name" >
    • <method description="Returns the scheme component of a URI. <pre><b>Example: </b> getScheme( "http://server.org/index.html" ) == "http"</pre>" name="getScheme" >
      • <return description="the scheme component, or null if not defined" type="java.lang.String" uitype="String" />
      • <param description="the URI" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Return the root of the filesystem that a URI belongs to. <pre><b>Example: </b> getRoot( "ftp://server.com/a/b/file.txt" ) == "ftp://server.com/" </pre>" name="getRoot" >
      • <return description="the URI of the filsystem root." type="java.net.URI" uitype="URI" />
      • <param description="the URI" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Return the name of a URI. This is just the last name in the path sequence. The root file of a file system has an empty name. <pre><b>Example: </b> getName( "ftp://server.com/a/b/file.txt ") == "file.txt" getName( "ftp://server.com/a/b/" ) == "b" getName( "ftp://server.com/" ) == "" </pre>" name="getName" >
      • <return description="The name. Never returns null." type="java.lang.String" uitype="String" />
      • <param description="the uri to extract a name from" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Returns the file extension of a URI. <pre><b>Example: </b> getExtension( "ftp://server.com/a/b/file.txt" ) == "txt" getExtension( "ftp://server.com/a/b/" ) == "" getExtension( "ftp://server.com/" ) == "" </pre>" name="getExtension" >
      • <return description="the extension of the file name, or null." type="java.lang.String" uitype="String" />
      • <param description="the uri to extract an extension from" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Returns the absolute path of a URI. This path is normalised, so that <tt>.</tt> and <tt>..</tt> elements have been removed. The path only contains <tt>/</tt> as its separator character and always starts with <tt>/</tt> The root of a file system has <tt>/</tt> as its absolute path. <pre><b>Example: </b> getPath( "ftp://server.com/a/b/file.txt" ) == "/a/b/file.txt" getPath( "ftp://server.com/a/b/" ) == "/a/b" getPath( "ftp://server.com/" ) == "/" getPath( "ftp://server.com/a/b/.././file.txt" ) == "/a/file.txt" </pre>" name="getPath" >
      • <return description="the path, never null." type="java.lang.String" uitype="String" />
      • <param description="the uri to extract the path from." name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Returns the URI of the parent (enclosing folder) of a URI. The root of a file system has no parent. <pre><b>Example: </b> getParent( "ftp://server.com/a/b/file.txt" ) == "ftp://server.com/a/b/" getParent( "ftp://server.com/a/b/" ) == "ftp://server.com/a/" </pre>" name="getParent" >
      • <return description="the parent of <tt>uri</tt>" type="java.net.URI" uitype="URI" />
      • <param description="" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Relativize a URI against a base URI. <pre><b>Example: </b> relativize( "ftp://server.com/a/b", "ftp://server.com/a/b/file.txt" ) == "file.txt" relativize( "ftp://server.com/", "ftp://server.com/a/b/file.txt" ) == "a/b/file.txt" relativize( "ftp://server.com/a/b/file.txt", "ftp://server.com/a/b" ) == ".." relativize( "ftp://server.com/a/b/file.txt", "ftp://server.com/" ) == "../../.." relativize( "ftp://server.com/a/b", "ftp://server.com/a/b ) == "." </pre><dl> <dt>Equivalent To:</dt><dd><tt> relativize( base, resolve( base, path ) ) == path</tt></dd></dl>" name="relativize" >
      • <return description="the relative path" type="java.lang.String" uitype="String" />
      • <param description="the base uri to relativize against" name="base" type="java.net.URI" uitype="URI" />
      • <param description="the uri to relativize" name="uri" type="java.net.URI" uitype="URI" />
      </method>
    • <method description="Resolve a path relative to a base URI. <pre><b>Example: </b> resolve( "ftp://server.com", "a/b/file.txt" ) == "ftp://server.com/a/b/file.txt" resolve( "ftp://server.com/a/b", ".." ) == "ftp://server.com/a" resolve( "ftp://server.com/a/b", "file.txt" ) == "ftp://server.com/a/b/file.txt" resolve( "ftp://server.com/a/b", "/file.txt" ) == "ftp://server.com/file.txt" </pre><dl> <dt>Equivalent To:</dt><dd><tt> resolve( base, relativize( base, url ) ) == url</tt></dd></dl>" name="resolve" >
      • <return description="the resulting resolved URI" type="java.net.URI" uitype="URI" />
      • <param description="the uri to resolve against" name="base" type="java.net.URI" uitype="URI" />
      • <param description="the path to resolve" name="path" type="java.lang.String" uitype="String" />
      </method>
    • <method description="Test whether one URI is an ancestor of another. <pre><b>Example: </b> isAncestor( "ftp://server.com/a/b/file.txt", "ftp://server.com" ) == True isAncestor( "ftp://server.com/a/b/file.txt", "ftp://server.com/a" ) == True isAncestor( "ftp://server.com/a/b", "ftp://server.com/a/b/file.txt" ) == False isAncestor( "ftp://server.com/a/b/file.txt", "ftp://server.com/a/b/file.txt" ) == False isAncestor( "ftp://server.com", "ftp://server.com" ) == False </pre>" name="isAncestor" >
      • <return description="boolean value" type="boolean" uitype="boolean" />
      • <param description="a uri" name="u" type="java.net.URI" uitype="URI" />
      • <param description="URI to test whether it ancestor of <tt>u</tt>" name="suspectedAncestor" type="java.net.URI" uitype="URI" />
      </method>
    </component>
  • <component description="Access information about the supported kinds of filesystem.<dl> <dt>See:</dt><dd> Manager, </dd></dl>" interface-class="org.astrogrid.acr.file.Systems" name="systems" >
    • <method description="List the URI schemes of the kinds of filesystem that Astro Runtime is able to access. This function can be used to trivially verify that input URIs will be readable by AR." name="listSchemes" >
      • <return description="a non-null array of URI schemes - expect to contain at least <tt>file</tt> ,<tt>http</tt>, <tt>ftp</tt>, <tt>sftp</tt>, <tt>ivo</tt>, <tt>vos</tt>." type="java.lang.String[]" uitype="String[]" />
      </method>
    </component>
</acr-module>

Back to master index