org.astrogrid.acr
Class Finder

java.lang.Object
  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