<acr-module description=" AstroGrid Services"
name=" astrogrid"
>
-
<component description="AR Service: Query remote databases and execute remote applications. The Common Execution Architecture (CEA) provides a uniform way to describe and execute astronomical applications and data services on the VO. This interface provides methods to <ul> <li>Discover available applications</li> <li>Build invocation documents containing the correct parameters</li> <li>Submit invocation documents for execution on remote servers</li> <li>Monitor progress and retreive results of execution</li> </ul> Each new application invocation is assigned a new globally unique id. These id's should be treated as opaque objects - the internal structure is still liable to change.<dl> <dt>See:</dt><dd> <a href="http://www.astrogrid.org/maven/docs/HEAD/applications/design/CEADesignIVOANote.html">Common Execution Architecture - IVOA Proposal</a> <br/>, <a href="http://www.astrogrid.org/maven/docs/HEAD/astrogrid-workflow-objects/schema/Workflow.html#element_tool">Tool Document Schema-Documentation</a>, <a href="http://www.astrogrid.org/maven/docs/HEAD/astrogrid-workflow-objects/schema/AGParameterDefinition.html#type_parameter">Value Parameter Element Schema-Documentation</a>, <a href="http://www.astrogrid.org/viewcvs/astrogrid/workflow-objects/schema/">XSD Schemas</a> <br/>, <a href="doc-files/run-app-demo.py">Calling CEA services - example python script</a>, <a href="doc-files/runAppDemo.groovy">Calling CEA services - example groovy script</a>, <a href="../dialogs/doc-files/example-tool.xml"> Example Tool Document</a> <br/>, org.astrogrid.acr.ui.ApplicationLauncher, org.astrogrid.acr.dialogs.ToolEditor, org.astrogrid.acr.astrogrid.ExecutionInformation, </dd></dl>"
interface-class="org.astrogrid.acr.astrogrid.Applications"
name="applications"
>
-
<method description="<b>Deprecated: </b>use <tt>getRegistryXQuery</tt><p /> list remote applications available in the registry.<dl> <dt>See:</dt><dd> #getCeaApplication, </dd></dl>"
excluded="true"
name="list"
>
-
<return description="a list of the registry identifiers of available applications"
type="java.net.URI[]"
uitype="URI[]"
/>
</method>
-
<method description="<b>Deprecated: </b>- use <tt>getRegistryXQuery</tt><p /> "
excluded="true"
name="getQueryToListApplications"
>
-
<return description=""
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="helper method - returns the SRQL query that should be passed to the registry to list all available applications. can be used as a starting point to build up filters, etc.<dl> <dt>See:</dt><dd> Registry#search(String), <a href='http://eurovotech.org/twiki/bin/view/VOTech/SimpleRegistryQueryLanguage'>SRQL Language Description</a>, </dd></dl>"
name="getRegistryQuery"
>
-
<return description="a SRQL query string."
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="<b>Deprecated: </b>use getRegistryXQuery<p /> helper method - returns the ADQL/s query that should be passed to the registry to list all available applications. can be used as a starting point to build up filters, etc.<dl> <dt>See:</dt><dd> org.astrogrid.acr.ivoa.Registry, </dd></dl>"
excluded="true"
name="getRegistryAdqlQuery"
>
-
<return description="an adql query string."
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="helper method - returns the Xquery that should be passed to the registry to list all available applications. can be used as a starting point to build up filters, etc.<dl> <dt>See:</dt><dd> org.astrogrid.acr.ivoa.Registry, </dd></dl>"
name="getRegistryXQuery"
>
-
<return description="an xquery string."
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="get information for a specific application from the registry. A convenience function for <tt>Registry#getResource(URI)</tt><dl> <dt>XMLRPC:</dt><dd> returns a structure containing attributes of <tt>CeaApplication</tt></dd></dl>"
name="getCeaApplication"
>
-
<return description="details of this application"
type="org.astrogrid.acr.astrogrid.CeaApplication"
uitype="CeaApplication"
/>
-
<param description="name of the application to hunt for"
name="applicationName"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="get formatted information about an application"
name="getDocumentation"
>
-
<return description="formatted, human-readable information about the application"
type="java.lang.String"
uitype="String"
/>
-
<param description=""
name="applicationName"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="create a template invocation document for a particular application. Examines the registry entry for this application, and constructs a template document containing fields for the required input and output parameters.<dl> <dt>XMLRPC:</dt><dd> will return xml document as a string</dd> <dt>See:</dt><dd> #createTemplateStruct(URI, String), #validate(Document), </dd></dl>"
name="createTemplateDocument"
>
-
<return description="a tool document. (xml form)"
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="the application to create the template for"
name="applicationName"
type="java.net.URI"
uitype="URI"
/>
-
<param description="interface of this application to create a template from."
name="interfaceName"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="create a template invocation datastucture for a particular application. Examines the registry entry for this application, and constructs a template document containing fields for the required input and output parameters. <br /> The datastructure returned is equivalent to the document returned by <tt>createTemplateDocument(URI, String)</tt> - this is a convenience method for scripting languages with minimal xml abilities.<dl> <dt>See:</dt><dd> #convertStructToDocument(Map), #validate(Document), </dd></dl>"
name="createTemplateStruct"
>
-
<return description="a tool object (structure)"
type="java.util.Map"
uitype="Map"
/>
-
<param description="the application to create the template for"
name="applicationName"
type="java.net.URI"
uitype="URI"
/>
-
<param description="interface of this application to create a template from."
name="interfaceName"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="convert a invocation document to a invocation structure. <br /> Translates an invocation document between two equvalent forms - a datastructure and a document<dl> <dt>See:</dt><dd> #convertStructToDocument(Map), </dd></dl>"
name="convertDocumentToStruct"
>
-
<return description="the equvalent tool structure"
type="java.util.Map"
uitype="Map"
/>
-
<param description="a tool document"
name="document"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="convert a invocation structure to the equivalent document.<dl> <dt>See:</dt><dd> #convertDocumentToStruct(Document), </dd></dl>"
name="convertStructToDocument"
>
-
<return description="the equivalent tool document"
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="a tool structure"
name="structure"
type="java.util.Map"
uitype="Map"
/>
</method>
-
<method description="Validate an invocation document against the application's description <br /> Verifies that all required parameters are present.<dl> <dt>See:</dt><dd> #createTemplateDocument(URI, String), </dd></dl>"
name="validate"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="tool document to validate"
name="document"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="Validate an invocation document (referenced by url) against an application description<dl> <dt>See:</dt><dd> #validate(Document), </dd></dl>"
name="validateStored"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="location of a resource containing the tool document to validate"
name="documentLocation"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="list the remote servers that provides a particular application. (It's possible, for CEA especially, that an application may be provided by multiple servers)"
name="listServersProviding"
>
-
<return description="list of registry summaries of cea servers that support this application"
type="org.astrogrid.acr.ivoa.resource.Service[]"
uitype="Service[]"
/>
-
<param description="registry identifier of the application to search servers for."
name="applicationId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#submit(Document)</tt><p /> submit an invocation document for execution.. No particular remote server is specified - the system will select a suitable one.<dl> <dt>See:</dt><dd> #submitStored(URI), #submitTo(Document, URI), </dd></dl>"
excluded="true"
name="submit"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description="tool document to execute"
name="document"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#submitTo(Document, URI)</tt><p /> submit an invocation document for execution on a named remote server.<dl> <dt>See:</dt><dd> #submitStored(URI), #submitStoredTo(URI, URI), </dd></dl>"
excluded="true"
name="submitTo"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description="tool document to execute"
name="document"
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="remote server to execute on"
name="server"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#submitStored(URI)</tt><p /> a variant of <tt>submit</tt> where invocation document is stored somewhere and referenced by URI."
excluded="true"
name="submitStored"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description="pointer to tool document - may be file:/, http://, ftp:// or ivo:// (myspace) protocols"
name="documentLocation"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#submitStoredTo(URI, URI)</tt><p /> variant of <tt>submitTo</tt> where tool document is referenced by URI. * @param documentLocation pointer to tool document - may be file:/, http://, ftp:// or ivo:// (myspace) protocols"
excluded="true"
name="submitStoredTo"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description=""
name="documentLocation"
type="java.net.URI"
uitype="URI"
/>
-
<param description="remote server to execute on"
name="server"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#halt(URI)</tt><p /> cancel execution of an application."
excluded="true"
name="cancel"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="id of execution to cancel"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#getExecutionInformation(URI)</tt><p /> retrive information about an application execution.<dl> <dt>XMLRPC:</dt><dd> will return a struct containing keys documented in <tt>ExecutionInformation</tt></dd></dl>"
excluded="true"
name="getExecutionInformation"
>
-
<return description="summary of this execution"
type="org.astrogrid.acr.astrogrid.ExecutionInformation"
uitype="ExecutionInformation"
/>
-
<param description="id of application to query"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>use <tt>RemoteProcessManager#getResults(URI)</tt><p /> retreive results of the application execution ."
excluded="true"
name="getResults"
>
-
<return description="results of this execution (name - value pairs). Note that this will only be the actual results for <b>direct</b> output parameters. For output parameters specified as <b>indirect</b>, the value returned will be the URI pointing to the location where the results are stored."
type="java.util.Map"
uitype="Map"
/>
-
<param description="id of application to query"
name="executionid"
type="java.net.URI"
uitype="URI"
/>
</method>
</component>
-
<component description="AR Service: Single sign-on and authentication. <p/> This implements a facade in front of the evolving IVOA single-sign-on mechanism.<dl> <dt>See:</dt><dd> <a href='http://www.ivoa.net/Documents/latest/SSOAuthMech.html'>IVOA Single-Sign On Specification</a>, </dd></dl>"
interface-class="org.astrogrid.acr.astrogrid.Community"
name="community"
>
-
<method description="login to virtual observatory. <pre><b>Example: </b> login("EdwardWoodward","ewarwoowar","uk.ac.le.star") </pre>"
name="login"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="user name (e.g. <tt>fredbloggs</tt>)"
name="username"
type="java.lang.String"
uitype="String"
/>
-
<param description="password for this user"
name="password"
type="java.lang.String"
uitype="String"
/>
-
<param description="community the user is registered with (e.g. <tt>uk.ac.astogrid</tt> )"
name="community"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="Access information about who the AR is currently logged in as.<dl> <dt>Note:</dt><dd> This method forces login if not already logged in</dd></dl>"
name="getUserInformation"
>
-
<return description="information about the current user."
type="org.astrogrid.acr.astrogrid.UserInformation"
uitype="UserInformation"
/>
</method>
-
<method description="logout of the virtual observatory"
name="logout"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
</method>
-
<method description="check whether AR is currently logged in."
name="isLoggedIn"
>
-
<return description="true if the user is logged in"
type="boolean"
uitype="boolean"
/>
</method>
-
<method description="display the login dialogue to prompt the user for input, and then log in."
name="guiLogin"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
</method>
</component>
-
<component description="AR Service: Execute and control workflows on remote job servers.<dl> <dt>See:</dt><dd> <a href="http://www.astrogrid.org/maven/docs/HEAD/jes/userguide-architecture.html">Workflow Userguide</a>, <a href="http://wiki.astrogrid.org/bin/view/Astrogrid/JesScriptingFAQ">Workflow Scripting FAQ</a> <br/>, <a href="http://www.astrogrid.org/maven/docs/HEAD/astrogrid-workflow-objects/schema/Workflow.html">Workflow Schema-Documentation</a>, <a href="http://www.astrogrid.org/maven/docs/HEAD/astrogrid-workflow-objects/schema/ExecutionRecord.html">Execution Record Schema-Document</a>, <a href="http://www.astrogrid.org/viewcvs/astrogrid/workflow-objects/schema/">XSD Schemas</a> <br/>, <a href="doc-files/example-workflow.xml">Example workflow</a>, <a href="doc-files/example-workflow-transcript.xml">Example execution transcript</a>, <a href="doc-files/example-workflow-transcript.html">Html-formatted execution transcript</a> <b/>, org.astrogrid.acr.astrogrid.Applications Information about executing single applications, org.astrogrid.acr.astrogrid.Myspace Information about distributed file storage, org.astrogrid.acr.astrogrid.RemoteProcessManager for more general process management - methods in this class are convenicne wrapper around operations in <tt>RemoteProcessManager</tt> <br/>, org.astrogrid.acr.ui.JobMonitor, org.astrogrid.acr.ui.WorkflowBuilder, org.astrogrid.acr.astrogrid.ExecutionInformation, </dd></dl>"
excluded="true"
interface-class="org.astrogrid.acr.astrogrid.Jobs"
name="jobs"
>
-
<method description="list the jobs for the current user."
name="list"
>
-
<return description="list of identifiers for the user's jobs (both current and completed jobs )"
type="java.net.URI[]"
uitype="URI[]"
/>
</method>
-
<method description="list summaries of the jobs for the current user.<dl> <dt>XMLRPC:</dt><dd> returns a struct. see <tt>ExecutionInformation</tt> for details of keys available.</dd></dl>"
name="listFully"
>
-
<return description="a beanful of information on each job"
type="org.astrogrid.acr.astrogrid.ExecutionInformation[]"
uitype="ExecutionInformation[]"
/>
</method>
-
<method description="create a new initialized workflow document, suitable as a starting point for building workflows."
name="createJob"
>
-
<return description="a workflow document - a <tt>workflow</tt> document in the the <tt>http://www.astrogrid.org/schema/AGWorkflow/v1</tt> namespace"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="wrap a remote application invocation document, to create a single-step workflow."
name="wrapTask"
>
-
<return description="a workflow document with a single step that executes the parameter task - a <tt>workflow</tt> document in the the <tt>http://www.astrogrid.org/schema/AGWorkflow/v1</tt> namespace"
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="- a task document in the <tt> http://www.astrogrid.org/schema/AGWorkflow/v1</tt> namespace"
name="taskDocument"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="retrieve the execution transcript for a job.<dl> <dt>XMLRPC:</dt><dd> returns a xml document string</dd></dl>"
name="getJobTranscript"
>
-
<return description="a workflow transcript document - A <tt>workflow</tt> document in the <tt>http://www.astrogrid.org/schema/AGWorkflow/v1</tt> namespace, annotated with execution information from the <tt>http://www.astrogrid.org/schema/ExecutionRecord/v1</tt> namespace."
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="the identifier of the job to retrieve"
name="jobURN"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="retrive summary for a job.<dl> <dt>XMLRPC:</dt><dd> returns a struct. see <tt>ExecutionInformation</tt> for details of keys available.</dd></dl>"
name="getJobInformation"
>
-
<return description="information about this job."
type="org.astrogrid.acr.astrogrid.ExecutionInformation"
uitype="ExecutionInformation"
/>
-
<param description="the identifier of the job to summarize"
name="jobURN"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="cancel the exeuciton of a running job."
name="cancelJob"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="identifier of the job to cancel."
name="jobURN"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="delete all record of a job from the job server."
name="deleteJob"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="identifier of the job to delete"
name="jobURN"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="submit a workflow for execution.<dl> <dt>XMLRPC:</dt><dd> pass the workflow parameter as a string</dd></dl>"
name="submitJob"
>
-
<return description="a unique identifier for this new job"
type="java.net.URI"
uitype="URI"
/>
-
<param description="workflow document to submit"
name="workflow"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="submit a workflow (stored in a file) for execution."
name="submitStoredJob"
>
-
<return description="a unique identifier for this new job."
type="java.net.URI"
uitype="URI"
/>
-
<param description="url refernce to the workflow document to submit (may be file://, http://, ftp:// or ivo:// - a myspace reference.)"
name="workflowReference"
type="java.net.URI"
uitype="URI"
/>
</method>
</component>
-
<component description="<b>Deprecated: </b>use <tt>Manager</tt><p /> AR Service: A distributed file storage system. <p/> Myspace is Astrogrid's prototype implementation of VOSpace. <blockquote><b>Warning: </b>This component just provides access to Myspace files. The <tt>Manager</tt> component provides access to a wider range of filesystems - VOSpace, Myspace, plus FTP and some others. </blockquote><dl> <dt>Note:</dt><dd> All resources in myspace are uniquely identified by a myspace resource identifier - which is an URI of form<br /> <tt>ivo://<i>Community-Id</i>/<i>User-Id</i>#<i>File-Path</i></tt>. <br />However, for convenience methods in this interface also accept an abridged form of reference - <tt>#<i>File-Path</i></tt> - 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.</dd> <dt>See:</dt><dd> #createFile Example of creating a file, #getReadContentURL Example of reading from a file, #getWriteContentURL Example of writing to a file, NodeInformation, MyspaceBrowser Myspace file browser component, ResourceChooser Dialogue for selecting myspace files, </dd></dl>"
interface-class="org.astrogrid.acr.astrogrid.Myspace"
name="myspace"
>
-
<method description="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."
name="getHome"
>
-
<return description="uri of the home folder - typically has form <tt>ivo://<i>Community-Id</i>/<i>User-Id</i>#</tt>"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="test whether a myspace resource exists."
name="exists"
>
-
<return description="true if the resource exists"
type="boolean"
uitype="boolean"
/>
-
<param description="uri to check (full or abridged form)"
name="filename"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="access metadata about a myspace resource. <blockquote><b>Warning: </b>At the moment, this is a costly operation </blockquote><dl> <dt>XMLRPC:</dt><dd> will return a map. see <tt>NodeInformation</tt> for available keys.</dd></dl>"
name="getNodeInformation"
>
-
<return description="a beanful of information"
type="org.astrogrid.acr.astrogrid.NodeInformation"
uitype="NodeInformation"
/>
-
<param description="resource to investigate"
name="filename"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="create a new myspace file. Any parent folders that are missing will be created too. <pre><b>Example: </b> "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) </pre> <pre><b>Example: </b> "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) </pre> }"
name="createFile"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="the resource to create."
name="filename"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="create a new myspace folder. Any parent folders that are missing will be created too."
name="createFolder"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="the resource to create."
name="foldername"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="create a child folder of the specified resource."
name="createChildFolder"
>
-
<return description="the ivorn of the new folder"
type="java.net.URI"
uitype="URI"
/>
-
<param description="parent of the new resource (must be a folder)"
name="parentFolder"
type="java.net.URI"
uitype="URI"
/>
-
<param description="name of the new folder"
name="name"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="create a child file of the specified resource."
name="createChildFile"
>
-
<return description="the ivorn of the new file"
type="java.net.URI"
uitype="URI"
/>
-
<param description="parent of the new resource (must be a folder)"
name="parentFolder"
type="java.net.URI"
uitype="URI"
/>
-
<param description="name of the new file"
name="name"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="retrieve the ID of the parent of a myspace resource."
name="getParent"
>
-
<return description="uri of the parent"
type="java.net.URI"
uitype="URI"
/>
-
<param description="uri of the resource to find parent for"
name="filename"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="list the names of the children (files and folders) of a myspace folder."
name="list"
>
-
<return description="an array of the names of the contents."
type="java.lang.String[]"
uitype="String[]"
/>
-
<param description="uri of the folder to inspect"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="list the identifiers of the children ( files and folders) of a myspace folder."
name="listIvorns"
>
-
<return description="an array of the ivorns of the contents."
type="java.net.URI[]"
uitype="URI[]"
/>
-
<param description="uri of the folder to inspect"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="list the node information objects for the children ( files and folders) of a myspace folder. <blockquote><b>Warning: </b>Expensive operation at present.</blockquote>"
name="listNodeInformation"
>
-
<return description="an array of the node information objects."
type="org.astrogrid.acr.astrogrid.NodeInformation[]"
uitype="NodeInformation[]"
/>
-
<param description="uri of the folder to inspect"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="refresh the metadata held about a myspace resource with the server. <blockquote><b>Note: </b> 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.</blockquote>"
name="refresh"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="resource to refresh"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="delete a myspace resource."
name="delete"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="uri of the resource to delete"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="rename a myspace resource."
name="rename"
>
-
<return description="uri pointing to the renamed resource (original uri may now be invalid)"
type="java.net.URI"
uitype="URI"
/>
-
<param description="uri of the resource to renam"
name="srcIvorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="new name for this resource"
name="newName"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="move a myspace resource."
name="move"
>
-
<return description="uri pointing to the moved resouce (original uri will now be invalid)"
type="java.net.URI"
uitype="URI"
/>
-
<param description="ivorn of the resource to move"
name="srcIvorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="ivorn of the new parent"
name="newParentIvorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="new name for this resource."
name="newName"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="<b>Deprecated: </b><p /> relocate a myspace resource to a different store. The relocated file remains in the same position in the user's myspace filetree. However, this method moves the data associated with the file from one filestore to another.<dl> <dt>See:</dt><dd> #listStores(), </dd></dl>"
excluded="true"
name="changeStore"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="uri of the resource to relocate"
name="srcIvorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="uri of the store server to relocat to."
name="storeIvorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="make a copy of a resource"
name="copy"
>
-
<return description="uri pointing to the resource copy"
type="java.net.URI"
uitype="URI"
/>
-
<param description="uri of the resource to copy"
name="srcIvorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="uri of the folder to copy to"
name="newParentIvorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="name to copy to"
name="newName"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="read the content of a myspace resource directly.<dl> <dt>Warning:</dt><dd> not a good idea for large files. in this case use <tt>copyContentToURL(URI, URL) </tt> or <tt>getReadContentURL(URI) </tt></dd></dl>"
name="read"
>
-
<return description="content of this resource (as a string)"
type="java.lang.String"
uitype="String"
/>
-
<param description="resource to read"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="Write data to a myspace resource.<dl> <dt>Warning:</dt><dd> not a good idea for large files. In this case use <tt>copyURLToContent(URL, URI) </tt></dd></dl>"
name="write"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="resource to write to"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="the data to write"
name="content"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="read the binary content of a myspace resource directly.<dl> <dt>Warning:</dt><dd> not a good idea for large files. in this case use <tt>copyContentToURL(URI, URL) </tt> or <tt>getReadContentURL(URI) </tt></dd></dl>"
name="readBinary"
>
-
<return description="byte array of the contents of this resource"
type="byte[]"
uitype="byte[]"
/>
-
<param description="resource to read"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="Write binary data to a myspace resource.<dl> <dt>Warning:</dt><dd> not a good idea for large files. In this case use <tt>copyURLToContent(URL, URI) </tt></dd></dl>"
name="writeBinary"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="resource to write to"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="the data to write"
name="content"
type="byte[]"
uitype="byte[]"
/>
</method>
-
<method description="Compute a URL which can then be read to access the contents (data) of a myspace resource. <pre><b>Example: </b> "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 </pre> <pre><b>Example: </b> "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.. </pre>"
name="getReadContentURL"
>
-
<return description="a url from which the contents of the resource can be read"
type="java.net.URL"
uitype="URL"
/>
-
<param description="resource to read"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="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 <tt>http://</tt> url, to which data should be <b>PUT</b> (not POST). <blockquote><b>Note: </b>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 <tt>transferCompleted</tt> </blockquote> Here's how to PUT and then notify of completion: <pre><b>Example: </b> "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. </pre><dl> <dt>See:</dt><dd> #transferCompleted, </dd></dl>"
name="getWriteContentURL"
>
-
<return description="a url to which the contents of the resource can be written"
type="java.net.URL"
uitype="URL"
/>
-
<param description="resource to write to"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="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 <tt>getWriteContentURL</tt>. There's no need to call this method when storing data using any other method<dl> <dt>See:</dt><dd> #getWriteContentURL, </dd></dl>"
name="transferCompleted"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="the myspace resource just written to"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="Copy the contents (data) of a resource out of myspace into a URL location."
name="copyContentToURL"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="the myspace resource to write out"
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
-
<param description="a writable URL - file:/, http:/ or ftp:/ protocol"
name="destination"
type="java.net.URL"
uitype="URL"
/>
</method>
-
<method description="Copy the contents (data) of a URL location into a myspace resource"
name="copyURLToContent"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="url to read data from - file:/, http:/ or ftp:/ protocol."
name="src"
type="java.net.URL"
uitype="URL"
/>
-
<param description="the myspace resource to store the data in."
name="ivorn"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b><p /> List the available filestores<dl> <dt>See:</dt><dd> #changeStore, </dd></dl>"
excluded="true"
name="listStores"
>
-
<return description="an array of service descriptions."
type="org.astrogrid.acr.ivoa.resource.Service[]"
uitype="Service[]"
/>
</method>
</component>
-
<component description="AR Service: A general manager for the execution , monitoring, and control of all remote processes. RemoteProcessManager unifies the functionality in <tt>org.astrogrid.acr.astrogrid.Jobs</tt> and <tt>org.astrogrid.acr.astrogrid.Applications</tt> and provides additional features - notably ability to register callbacks for progress notifications. It is still valid to use the <tt>Jobs</tt> or <tt>Applications</tt>, however, this interface also knows how to invoke other kinds of service, and provides a uniform interface to cea, cone, siap, ssap services.<dl> <dt>Note:</dt><dd> As JES is no longer supported, and we no longer provide cea-style querying of cone and siap, maybe this interface should be retired?</dd></dl>"
interface-class="org.astrogrid.acr.astrogrid.RemoteProcessManager"
name="processManager"
>
-
<method description="list current remote processes belonging to the current user"
name="list"
>
-
<return description="list of identifiers for the user's remote processes that are currently being managed by AR"
type="java.net.URI[]"
uitype="URI[]"
/>
</method>
-
<method description="Submit a document for execution. No particular server is specified - the system will choose a suitable server.<dl> <dt>See:</dt><dd> #submitStored(URI), #submitTo(Document, URI), </dd></dl>"
name="submit"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description="the document to execute - a program / script / workflow / tool document"
name="document"
type="org.w3c.dom.Document"
uitype="XML"
/>
</method>
-
<method description="Submit a document for execution on a named server<dl> <dt>See:</dt><dd> #submitStored(URI), #submitStoredTo(URI, URI), </dd></dl>"
name="submitTo"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description="the document to execute - a workflow, cea task, etc"
name="document"
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="server to execute on"
name="server"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="variant of <tt>submit</tt> where document is stored somewhere and referenced by URI"
name="submitStored"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description="pointer to document - may be file:/, http://, ftp:// or ivo:// (myspace) protocols"
name="documentLocation"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="variant of <tt>submitTo</tt> where document is referenced by URL * @param documentLocation pointer to tool document - may be file:/, http://, ftp:// or ivo:// (myspace) protocols"
name="submitStoredTo"
>
-
<return description="a new unique execution id"
type="java.net.URI"
uitype="URI"
/>
-
<param description=""
name="documentLocation"
type="java.net.URI"
uitype="URI"
/>
-
<param description="to execute on"
name="server"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="halt execution of a process"
name="halt"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="id of execution to cancel"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="delete all record of a process"
name="delete"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="identifier of the process to delete"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="get information about an process execution<dl> <dt>XMLRPC:</dt><dd> will return a struct containing keys documented in <tt>ExecutionInformation</tt></dd></dl>"
name="getExecutionInformation"
>
-
<return description="summary of this execution"
type="org.astrogrid.acr.astrogrid.ExecutionInformation"
uitype="ExecutionInformation"
/>
-
<param description="id of application to query"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="return the messages received from a remote process<dl> <dt>XMLRPC:</dt><dd> will return a list of structs containing keys documented in {@ExecutionMessage}</dd></dl>"
name="getMessages"
>
-
<return description="an array of all messages received from process"
type="org.astrogrid.acr.astrogrid.ExecutionMessage[]"
uitype="ExecutionMessage[]"
/>
-
<param description="id of process to query/"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="Retreive results of the application execution"
name="getResults"
>
-
<return description="results of this execution (name - value pairs). Note that this will only be the actual results for <b>direct</b> output parameters. For output parameters specified as <b>indirect</b>, the value returned will be the URI pointing to the location where the results are stored."
type="java.util.Map"
uitype="Map"
/>
-
<param description="id of application to query"
name="executionid"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="convenience method to retreive a single result from an application executioin. equaivalent to <tt>getResults(execId).get(resultName)</tt>, but may be more convenient from some scripting languages, or cases where there's only a single result returned."
name="getSingleResult"
>
-
<return description="a result. Never null."
type="java.lang.String"
uitype="String"
/>
-
<param description="id of the application to query"
name="executionId"
type="java.net.URI"
uitype="URI"
/>
-
<param description="name of the result to return. If the name is null or unrecognized AND this application only returns one result, that is returned."
name="resultName"
type="java.lang.String"
uitype="String"
/>
</method>
</component>
-
<component description="AR Service: Query for <b>Time series data</b> from Simple Time Access Protocol (STAP) services (DAL). <p /> <blockquote><b>Note: </b>This class provides functions to construct a DAL query. To execute that query, see the examples and methods in the <tt>Dal</tt> class. </blockquote> <h2>Example</h2> The following example constructs a queryURL, performs the query, and then downloads the first of the resulting datasets. See <tt>Dal</tt> for other things that can be done with a query URL. <pre><b>Example: </b> "Query a Stap service and download a subset of the data (Python)" # connect to the AR from xmlrpc import Server, DateTime from os.path import expanduser ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc') stap = ar.ivoa.stap #take a reference to the AR STAP component #the STAP service to query (selected using voexplorer) service = "ivo://mssl.ucl.ac.uk/stap-lasco" #build a query start = DateTime('20000101T00:00:00') end = DateTime('20000102T00:00:00') query = stap.constructQuery(service,start,end) print "QueryURL",query #execute the query rows = stap.execute(query) #inspect what we've got. print "Rows Returned",len(rows) import pprint pprint.pprint(rows[0]) #download first datasets into current directory #compute url for current directory from urlparse import urlunsplit from os import getcwd currentDirURL = urlunsplit(['file','',getcwd(),'','']) print "Downloading data to",currentDirURL stap.saveDatasetsSubset(query,currentDirURL,[0]) </pre> The output from this script is shown below. <pre> QueryURL http://msslxx.mssl.ucl.ac.uk:8080/stap-lasco/StapSearch?service=astrogrid_stap&START=2000-01-01T00%3A00%3A00&END=2000-01-02T00%3A00%3A00 Rows Returned 3 {'Concept': ' Coronal Mass Ejection', 'Contact Email': ' eca@mssl.ucl.ac.uk', 'Contact Name': ' Elizabeth Auden', 'INST_ID': 'SOHO_LASCO', 'IVORN': 'ivo://mssl.ucl.ac.uk/LASCO#LASCO20000101T065405_21', 'Name': ' LASCO_20000101T065405_21', 'Parameters': ' Central Position Angle=21 deg, Angular Width=76 deg, Linear Speed=337 km/s, Acceleration=8.8 m/s^2, Mass=5.0e+15 g, Kinetic Energy=2.8e+30 erg, Measurement Position Angle=11 deg', 'References': ' C2 movie=http://lasco-www.nrl.navy.mil/daily_mpg/2000_01/000101_c2.mpg, C3 movie=http://lasco-www.nrl.navy.mil/daily_mpg/2000_01/000101_c3.mpg, SXT movie=http://cdaw.gsfc.nasa.gov/CME_list/daily_mpg/2000_01/sxt_almg.20000101.mpg, PHTX movie=http://cdaw.gsfc.nasa.gov/CME_list/daily_plots/sephtx/2000_01/sephtx.20000101.png, Java movie=http://cdaw.gsfc.nasa.gov/CME_list/daily_movies/2000/01/01, C2 movie / GOES light curve=http://cdaw.gsfc.nasa.gov/CME_list/UNIVERSAL/2000_01/jsmovies/2000_01/20000', 'VOX:AccessReference': ' http://msslxx.mssl.ucl.ac.uk:8080/voevent/xml/LASCO/LASCO_20000101T065405_21.xml', 'VOX:Format': 'VOEVENT', 'meta': 'LASCO CME VOEvents', 'meta.curation': 'CDAW (NASA/Goddard), via MSSL query', 'meta.ref.url': 'http://cdaw.gsfc.nasa.gov/CME_list/', 'meta.title': 'LASCO CMEs', 'time.obs.end': '2000-01-01T06:54:05', 'time.obs.start': '2000-01-01T06:54:05'} Downloading data to file:///Users/noel/Documents/workspace/python </pre><dl> <dt>See:</dt><dd> <a href="http://wiki.astrogrid.org/bin/view/Astrogrid/SimpleTimeAccessProtocol">Proposed STAP Standard</a>, Dal, Sesame Sesame - resolves object names to RA,Dec positions, #getRegistryXQuery() getRegistryXQuery() - a query to list all STAP Services., </dd></dl>"
interface-class="org.astrogrid.acr.astrogrid.Stap"
name="stap"
>
-
<method description="Construct a STAP Query on Time."
name="constructQuery"
>
-
<return description="A query URL. The query can then be performed by either <ul> <li> programmatically performing a HTTP GET on the query URL </li> <li> passing the query URL to one of the <tt>Dal</tt> <tt>execute</tt> methods - such as <tt>executeAndSave(URL, URI)</tt> </li> </ul>"
type="java.net.URL"
uitype="URL"
/>
-
<param description="Resource Identifier <i>or</i> URL of the Service to query. <i>Prefer providing a Resource Identifier, as this insulates against changes in service endpoint</i>. <blockquote><dl> <dt>Resource Identifier</dt><dd> The resource ID of the STAP service to query, as returned by <tt>Resource#getId()</tt>. Example: <tt>ivo://mssl.ucl.ac.uk/stap-hinode-eis_2</tt> <br/>The <tt>Registry</tt> will be queried to resolve the resource ID into a <tt>Resource</tt> object, from which the <tt>StapCapability</tt> will be found, from which in turn the first <tt>AccessURL</tt> will be used. </dd> <dt>URL of the Service</dt><dd> The endpoint URL. Can be any <tt>http://</tt> URL. </dd> </dl></blockquote>"
name="service"
type="java.net.URI"
uitype="URI"
/>
-
<param description="start date and time"
name="start"
type="java.util.Date"
uitype="Date"
/>
-
<param description="end date and time"
name="end"
type="java.util.Date"
uitype="Date"
/>
</method>
-
<method description="Construct a STAP Query on Time and Format."
name="constructQueryF"
>
-
<return description="A query URL. The query can then be performed by either <ul> <li> programmatically performing a HTTP GET on the query URL </li> <li> passing the query URL to one of the <tt>Dal</tt> <tt>execute</tt> methods - such as <tt>executeAndSave(URL, URI)</tt> </li> </ul>"
type="java.net.URL"
uitype="URL"
/>
-
<param description="Resource Identifier <i>or</i> URL of the Service to query. <i>Prefer providing a Resource Identifier, as this insulates against changes in service endpoint</i>. <blockquote><dl> <dt>Resource Identifier</dt><dd> The resource ID of the STAP service to query, as returned by <tt>Resource#getId()</tt>. Example: <tt>ivo://mssl.ucl.ac.uk/stap-hinode-eis_2</tt> <br/>The <tt>Registry</tt> will be queried to resolve the resource ID into a <tt>Resource</tt> object, from which the <tt>StapCapability</tt> will be found, from which in turn the first <tt>AccessURL</tt> will be used. </dd> <dt>URL of the Service</dt><dd> The endpoint URL. Can be any <tt>http://</tt> URL. </dd> </dl></blockquote>"
name="service"
type="java.net.URI"
uitype="URI"
/>
-
<param description="start date and time"
name="start"
type="java.util.Date"
uitype="Date"
/>
-
<param description="end date and time"
name="end"
type="java.util.Date"
uitype="Date"
/>
-
<param description="format of images or time series data e.g. <tt>ALL</tt>"
name="format"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="Construct a STAP Query on Time and Position"
name="constructQueryP"
>
-
<return description="A query URL. The query can then be performed by either <ul> <li> programmatically performing a HTTP GET on the query URL </li> <li> passing the query URL to one of the <tt>Dal</tt> <tt>execute</tt> methods - such as <tt>executeAndSave(URL, URI)</tt> </li> </ul>"
type="java.net.URL"
uitype="URL"
/>
-
<param description="Resource Identifier <i>or</i> URL of the Service to query. <i>Prefer providing a Resource Identifier, as this insulates against changes in service endpoint</i>. <blockquote><dl> <dt>Resource Identifier</dt><dd> The resource ID of the STAP service to query, as returned by <tt>Resource#getId()</tt>. Example: <tt>ivo://mssl.ucl.ac.uk/stap-hinode-eis_2</tt> <br/>The <tt>Registry</tt> will be queried to resolve the resource ID into a <tt>Resource</tt> object, from which the <tt>StapCapability</tt> will be found, from which in turn the first <tt>AccessURL</tt> will be used. </dd> <dt>URL of the Service</dt><dd> The endpoint URL. Can be any <tt>http://</tt> URL. </dd> </dl></blockquote>"
name="service"
type="java.net.URI"
uitype="URI"
/>
-
<param description="start date and time"
name="start"
type="java.util.Date"
uitype="Date"
/>
-
<param description="end date and time"
name="end"
type="java.util.Date"
uitype="Date"
/>
-
<param description="right ascension e.g <tt>6.950</tt>"
name="ra"
type="double"
uitype="double"
/>
-
<param description="declination e.g. <tt>-1.6</tt>"
name="dec"
type="double"
uitype="double"
/>
-
<param description="radius of cone e.g. <tt>0.1</tt>"
name="size"
type="double"
uitype="double"
/>
</method>
-
<method description="Construct a STAP Query on Time, Position and Format"
name="constructQueryPF"
>
-
<return description="A query URL. The query can then be performed by either <ul> <li> programmatically performing a HTTP GET on the query URL </li> <li> passing the query URL to one of the <tt>Dal</tt> <tt>execute</tt> methods - such as <tt>executeAndSave(URL, URI)</tt> </li> </ul>"
type="java.net.URL"
uitype="URL"
/>
-
<param description="Resource Identifier <i>or</i> URL of the Service to query. <i>Prefer providing a Resource Identifier, as this insulates against changes in service endpoint</i>. <blockquote><dl> <dt>Resource Identifier</dt><dd> The resource ID of the STAP service to query, as returned by <tt>Resource#getId()</tt>. Example: <tt>ivo://mssl.ucl.ac.uk/stap-hinode-eis_2</tt> <br/>The <tt>Registry</tt> will be queried to resolve the resource ID into a <tt>Resource</tt> object, from which the <tt>StapCapability</tt> will be found, from which in turn the first <tt>AccessURL</tt> will be used. </dd> <dt>URL of the Service</dt><dd> The endpoint URL. Can be any <tt>http://</tt> URL. </dd> </dl></blockquote>"
name="service"
type="java.net.URI"
uitype="URI"
/>
-
<param description="start date and time"
name="start"
type="java.util.Date"
uitype="Date"
/>
-
<param description="end date and time"
name="end"
type="java.util.Date"
uitype="Date"
/>
-
<param description="right ascension e.g <tt>6.950</tt>"
name="ra"
type="double"
uitype="double"
/>
-
<param description="declination e.g. <tt>-1.6</tt>"
name="dec"
type="double"
uitype="double"
/>
-
<param description="radius of cone e.g. <tt>0.1</tt>"
name="size"
type="double"
uitype="double"
/>
-
<param description="format of images or time series data e.g. <tt>ALL</tt>"
name="format"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="Construct a STAP Query on Time and full Position"
name="constructQueryS"
>
-
<return description="A query URL. The query can then be performed by either <ul> <li> programmatically performing a HTTP GET on the query URL </li> <li> passing the query URL to one of the <tt>Dal</tt> <tt>execute</tt> methods - such as <tt>executeAndSave(URL, URI)</tt> </li> </ul>"
type="java.net.URL"
uitype="URL"
/>
-
<param description="Resource Identifier <i>or</i> URL of the Service to query. <i>Prefer providing a Resource Identifier, as this insulates against changes in service endpoint</i>. <blockquote><dl> <dt>Resource Identifier</dt><dd> The resource ID of the STAP service to query, as returned by <tt>Resource#getId()</tt>. Example: <tt>ivo://mssl.ucl.ac.uk/stap-hinode-eis_2</tt> <br/>The <tt>Registry</tt> will be queried to resolve the resource ID into a <tt>Resource</tt> object, from which the <tt>StapCapability</tt> will be found, from which in turn the first <tt>AccessURL</tt> will be used. </dd> <dt>URL of the Service</dt><dd> The endpoint URL. Can be any <tt>http://</tt> URL. </dd> </dl></blockquote>"
name="service"
type="java.net.URI"
uitype="URI"
/>
-
<param description="start date and time"
name="start"
type="java.util.Date"
uitype="Date"
/>
-
<param description="end date and time"
name="end"
type="java.util.Date"
uitype="Date"
/>
-
<param description="right ascension e.g <tt>6.950</tt>"
name="ra"
type="double"
uitype="double"
/>
-
<param description="declination e.g. <tt>-1.6</tt>"
name="dec"
type="double"
uitype="double"
/>
-
<param description="size of ra e.g. <tt>0.1</tt>"
name="ra_size"
type="double"
uitype="double"
/>
-
<param description="size of dec e.g. <tt>0.2</tt>"
name="dec_size"
type="double"
uitype="double"
/>
</method>
-
<method description="Construct a STAP Query on Time, full Position, and Format"
name="constructQuerySF"
>
-
<return description="A query URL. The query can then be performed by either <ul> <li> programmatically performing a HTTP GET on the query URL </li> <li> passing the query URL to one of the <tt>Dal</tt> <tt>execute</tt> methods - such as <tt>executeAndSave(URL, URI)</tt> </li> </ul>"
type="java.net.URL"
uitype="URL"
/>
-
<param description="Resource Identifier <i>or</i> URL of the Service to query. <i>Prefer providing a Resource Identifier, as this insulates against changes in service endpoint</i>. <blockquote><dl> <dt>Resource Identifier</dt><dd> The resource ID of the STAP service to query, as returned by <tt>Resource#getId()</tt>. Example: <tt>ivo://mssl.ucl.ac.uk/stap-hinode-eis_2</tt> <br/>The <tt>Registry</tt> will be queried to resolve the resource ID into a <tt>Resource</tt> object, from which the <tt>StapCapability</tt> will be found, from which in turn the first <tt>AccessURL</tt> will be used. </dd> <dt>URL of the Service</dt><dd> The endpoint URL. Can be any <tt>http://</tt> URL. </dd> </dl></blockquote>"
name="service"
type="java.net.URI"
uitype="URI"
/>
-
<param description="start date and time"
name="start"
type="java.util.Date"
uitype="Date"
/>
-
<param description="end date and time"
name="end"
type="java.util.Date"
uitype="Date"
/>
-
<param description="right ascension e.g <tt>6.950</tt>"
name="ra"
type="double"
uitype="double"
/>
-
<param description="declination e.g. <tt>-1.6</tt>"
name="dec"
type="double"
uitype="double"
/>
-
<param description="size of ra e.g. <tt>0.1</tt>"
name="ra_size"
type="double"
uitype="double"
/>
-
<param description="size of dec e.g. <tt>0.2</tt>"
name="dec_size"
type="double"
uitype="double"
/>
-
<param description="format of images or time series data e.g. <tt>ALL</tt>"
name="format"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="Add an additional option to a previously constructed query. <p/> Sometimes neccessary, for some DAL protocols, to provide optional query parameters."
name="addOption"
>
-
<return description="<tt>query</tt> with the option appended."
type="java.net.URL"
uitype="URL"
/>
-
<param description="the query url"
name="query"
type="java.net.URL"
uitype="URL"
/>
-
<param description="name of the option to add"
name="optionName"
type="java.lang.String"
uitype="String"
/>
-
<param description="value for the new option"
name="optionValue"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="Execute a DAL query, returning a datastructure<dl> <dt>Note:</dt><dd> When querying a SIAP service, the result uses keys drawn from the SIAP dataset datamodel</dd></dl>"
name="execute"
>
-
<return description="The service response parsed as a list of of rows. Each row is represented is a map between UCD or datamodel keys and values from the response"
type="java.util.Map[]"
uitype="Map[]"
/>
-
<param description="query url to execute"
name="query"
type="java.net.URL"
uitype="URL"
/>
</method>
-
<method description="Execute a DAL query, returning a Votable document.<dl> <dt>Note:</dt><dd> This is a convenience method that just performs a 'GET' on the query url. Many programming languages support this functionality internally.</dd></dl>"
name="executeVotable"
>
-
<return description="a votable document."
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description="query url to execute"
name="query"
type="java.net.URL"
uitype="URL"
/>
</method>
-
<method description="<b>Deprecated: </b>- use executeVotable()<p /> "
excluded="true"
name="getResults"
>
-
<return description=""
type="org.w3c.dom.Document"
uitype="XML"
/>
-
<param description=""
name="url"
type="java.net.URL"
uitype="URL"
/>
</method>
-
<method description="Execute a DAL query and save the resulting document.<dl> <dt>Note:</dt><dd> in the case of saving to myspace, the myspace server performs the query - the data does not pass through the user's computer.</dd> <dt>See:</dt><dd> Systems#listSchemes() List of supported URI schemes for <tt>saveLocation</tt>, </dd></dl>"
name="executeAndSave"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description="query url to execute"
name="query"
type="java.net.URL"
uitype="URL"
/>
-
<param description="location to save result document - For example a <tt>file:/</tt>, <tt>ivo://</tt> (myspace), <tt>ftp://</tt> location"
name="saveLocation"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="<b>Deprecated: </b>- use executeAndSave()<p /> "
excluded="true"
name="saveResults"
>
-
<return description=""
type="java.lang.Void"
uitype="void"
/>
-
<param description=""
name="url"
type="java.net.URL"
uitype="URL"
/>
-
<param description=""
name="saveLocation"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="Execute a DAL query, and save the datasets referenced by the response. <p /> Applies to those DAL protocols (<tt>Siap</tt>, <tt>Ssap</tt>, <tt>Stap</tt>) where the response points to external data files.<dl> <dt>Note:</dt><dd> In the case of saving to myspace or vospace, the myspace server performs the query and dataset download - the data does not pass through the user's computer.</dd> <dt>See:</dt><dd> Siap Example of Use, Systems#listSchemes() List of supported URI schemes for <tt>saveLocation</tt>, </dd></dl>"
name="saveDatasets"
>
-
<return description="number of datasets saved."
type="int"
uitype="int"
/>
-
<param description="query url to execute"
name="query"
type="java.net.URL"
uitype="URL"
/>
-
<param description="location of a directory in which to save the datasets. May be any of the filesystem types listed in <tt>Systems#listSchemes()</tt>."
name="saveLocation"
type="java.net.URI"
uitype="URI"
/>
</method>
-
<method description="Execute a DAL query, and save a subset of the datasets referenced by the response. <p /> Applies to those DAL protocols (<tt>Siap</tt>, <tt>Ssap</tt>, <tt>Stap</tt>) where the response points to external data files.<dl> <dt>Note:</dt><dd> in the case of saving to myspace or vospace, the myspace server performs the query and dataset download - the data does not pass through the user's computer.</dd> <dt>See:</dt><dd> Systems#listSchemes() List of supported URI schemes for <tt>saveLocation</tt>, </dd></dl>"
name="saveDatasetsSubset"
>
-
<return description="number of datasets saved."
type="int"
uitype="int"
/>
-
<param description="the DAL query"
name="query"
type="java.net.URL"
uitype="URL"
/>
-
<param description="location of a directory in which to save the datasets. May be any of the filesystem types listed in <tt>Systems#listSchemes()</tt>."
name="saveLocation"
type="java.net.URI"
uitype="URI"
/>
-
<param description="list of Integers - indexes of the rows in the query response for which to save the dataset. (0= first row)"
name="rows"
type="java.util.List"
uitype="List"
/>
</method>
-
<method description="Returns a SRQL query that, when passed to the registry, will return all know services of that type. <br/> can be used as a starting point for filters, etc. <blockquote><b>Warning: </b>In the case of <tt>Cone</tt> the registry query will return far too many to be useful - it is necessary to use this xquery as a starting point for building a more tightly-constrained query.</blockquote> <pre><b>Example: </b> "Example of querying for cone services related to 'dwarf'" # connect to the AR from xmlrpc import Server from os.path import expanduser ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc') #call this method to get a query to list all Cone-search services. coneQuery = ar.ivoa.cone.getRegistryQuery() #combine it into a more tightly contrained query myQuery = coneQuery + ' and subject=dwarf' # perform the query rs = ar.ivoa.registry.searcg(myQuery) #inspect the results print len(rs) for r in rs: print r['id'] </pre><dl> <dt>See:</dt><dd> <a href='http://eurovotech.org/twiki/bin/view/VOTech/SimpleRegistryQueryLanguage'>SRQL Language Description</a>, #getRegistryXQuery() alternative that returns an XQuery, </dd></dl>"
name="getRegistryQuery"
>
-
<return description="a SRQL query string"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="<b>Deprecated: </b><p /> helper method - returns an ADQL/s query that should be passed to a registry to list all available DAL services of this type. <br/> can be used as a starting point for filters, etc."
excluded="true"
name="getRegistryAdqlQuery"
>
-
<return description="an adql query string"
type="java.lang.String"
uitype="String"
/>
</method>
-
<method description="Return an XQuery that, when passed to the registry, will return all known services of that type. <blockquote><b>Warning: </b>In the case of <tt>Cone</tt> the registry query will return far too many to be useful - it is necessary to use this xquery as a starting point for building a more tightly-constrained query.</blockquote> <pre><b>Example: </b> "Example of querying for cone services related to 'dwarf'" # connect to the AR from xmlrpc import Server from os.path import expanduser ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc') #call this method to get a query to list all Cone-search services. coneQuery = ar.ivoa.cone.getRegistryXQuery() #combine it into a more tightly contrained query myQuery = "let $cq := " + coneQuery + """ for $r in $cq where contains($r/content/subject,'dwarf') return $r """ # perform the query rs = ar.ivoa.registry.xquerySearch(myQuery) #inspect the results print len(rs) for r in rs: print r['id'] </pre> the output of this script is <pre> 2 ivo://nasa.heasarc/rasswd ivo://nasa.heasarc/mcksion </pre><dl> <dt>See:</dt><dd> #getRegistryQuery() alternative that returns a SRQL query., <a href="http://www.w3schools.com/xquery/default.asp">XQuery Language Tutorial</a>, </dd></dl>"
name="getRegistryXQuery"
>
-
<return description="an xquery string"
type="java.lang.String"
uitype="String"
/>
</method>
</component>
</acr-module> |