org.astrogrid.acr
Class Finder

java.lang.Object
  extended by org.astrogrid.acr.Finder

public class Finder
extends Object

Connect to an AstroRuntime Instance using RMI. The Astro Runtime instance is found by

  1. First attempting to connect to a running instance using RMI, on a port defined in the file ~/.acr-rmi-port (this file is written by a running AR instance)
  2. failing that, tries to create an instance internally (which will only work if implementation classes are on classpath),
  3. failing that, will prompt the user to start an instance of the AR
The interface returned will either be a RMI stub or direct instance, depending on how the AR was found. No matter how the AR is found, the ACR interface returned is a singleton - it is stored in this class for simple access the next time

Connecting to AstroRuntime

import org.astrogrid.acr.builtin.ACR;
import org.astrogrid.acr.Finder;
Finder f = new Finder();
ACR acr = f.find(); // find the AR 

Notes:
This class can also be used for direct-java connection to an AstroRuntime, if the AR is running in the same JVM as the calling code.
See Also:
How to retrieve services from the ACR interface
XMLRPC
This class is not used for XML-RPC connections to AstroRuntime. For instructions for Python, Perl, C, etc see the overview documentation.

Constructor Summary
Finder()
          Construct a new Finder
 
Method Summary
static File configurationFile()
          The AR RMI connection file.
 ACR find()
          Find or create an Astro Runtime (AR) instance.
 ACR find(boolean tryToStartIfNotRunning, boolean warnUserBeforeStarting)
          Find or create an Astro Runtime (AR) instance.
 ACR findSession(String sessionId)
          Find an Astro Runtime instance for a specific session.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Finder

public Finder()
Construct a new Finder

Method Detail

find

public ACR find()
         throws ACRException
Find or create an Astro Runtime (AR) instance.

Equivalent To:
findSession(true,false)
Notes:
The instance returned is a singleton - i.e. all subsequent calls to this method will return the same object.
Returns:
an interface to the Astro Runtime - depending on how connected will either be a direct instance or a remote stub - although this makes no difference to the consumer.
Throws:
ACRException - if all options fail

findSession

public ACR findSession(String sessionId)
                throws InvalidArgumentException,
                       NotApplicableException,
                       ServiceException
Find an Astro Runtime instance for a specific session. Unlike Finder.find() this method will not start the Astro Runtime service if it is not already running - the Astro Runtime must be running first.

Warnings:
Still Experimental.
Parameters:
sessionId - the identifier of a current session
See Also:
SessionManager
Returns:
an AR instance that is connected to the specified session
Throws:
InvalidArgumentException - if the sessionId is invalid.
NotApplicableException - if a connection has not already been made to an AR instance, or AR is an older version without session support
ServiceException - if there is an error connecting to this session.

find

public ACR find(boolean tryToStartIfNotRunning,
                boolean warnUserBeforeStarting)
         throws ACRException
Find or create an Astro Runtime (AR) instance.

Parameters:
tryToStartIfNotRunning - if false, will not attempt to start an AR, but instead will return NULL if there isn't an instance already running
warnUserBeforeStarting - if true, will warn the user before attempting to start an AR, giving them the chance to start one manually
See Also:
Finder.find()
Returns:
an instance of the Astro Runtime
Throws:
ACRException

configurationFile

public static final File configurationFile()
The AR RMI connection file.

This is ~/.acr-rmi-port



Copyright © 2002-2010 AstroGrid. All Rights Reserved.