org.astrogrid.samp.hub
Class Hub

java.lang.Object
  extended by org.astrogrid.samp.hub.Hub

public class Hub
extends Object

Class which starts and stops a hub and its associated profiles. Static methods are provided for starting a hub in the current or an external JVM, and a main() method is provided for use from the command line.

Some of the static methods allow you to indicate which hub profiles should be used, others use a default. The default list can be set programmatically by using the setDefaultProfileClasses(java.lang.Class[]) method or externally by using the "jsamp.hub.profiles" system property. So, for instance, running an application with -Djsamp.hub.profiles=web,std will cause it to run hubs using both the Standard and Web profiles if it does not explicitly choose profiles.

Since:
31 Jan 2011
Author:
Mark Taylor

Field Summary
static String HUBPROFILES_PROP
          System property name for supplying default profiles ("jsamp.hub.profiles").
 
Constructor Summary
Hub(HubService service, HubProfile[] profiles)
          Constructor.
 
Method Summary
static void checkExternalHubAvailability()
          Attempts to determine whether an external hub can be started using runExternalHub.
static HubProfile[] createDefaultProfiles()
          Returns an array of default Hub Profiles.
static Class[] getDefaultProfileClasses()
          Returns a copy of the default set of HubProfile classes used when a hub is run and the list of profiles is not set explicitly.
static HubProfileFactory[] getKnownHubProfileFactories()
          Returns a standard list of known HubProfileFactories.
static void main(String[] args)
          Main method, which allows configuration of which profiles will run and configuration of those individual profiles.
static HubProfileFactory[] parseProfileList(String listTxt)
          Parses a string representing a list of hub profiles.
static void runExternalHub(HubServiceMode hubMode)
          Attempts to run a hub in a new JVM with a default set of profiles.
static void runExternalHub(HubServiceMode hubMode, Class[] profileClasses)
          Attempts to start a hub in a new JVM with a given set of profiles.
static Hub runHub(HubServiceMode hubMode)
          Starts a SAMP hub with a default set of profiles.
static Hub runHub(HubServiceMode hubMode, HubProfile[] profiles)
          Starts a SAMP hub with a given set of profiles.
static int runMain(String[] args)
          Invoked by main.
static void setDefaultProfileClasses(Class[] dfltProfileClasses)
          Sets the default set of HubProfile classes.
 void shutdown()
          Stops this hub and its profiles running.
 void start()
          Starts this hub and its profiles running.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HUBPROFILES_PROP

public static final String HUBPROFILES_PROP
System property name for supplying default profiles ("jsamp.hub.profiles"). The value of this property, if any, will be fed to parseProfileList(java.lang.String).

See Also:
Constant Field Values
Constructor Detail

Hub

public Hub(HubService service,
           HubProfile[] profiles)
Constructor.

Parameters:
service - hub service
profiles - hub profiles for access from clients
Method Detail

start

public void start()
           throws IOException
Starts this hub and its profiles running.

Throws:
IOException

shutdown

public void shutdown()
Stops this hub and its profiles running.


getKnownHubProfileFactories

public static HubProfileFactory[] getKnownHubProfileFactories()
Returns a standard list of known HubProfileFactories. This is used when parsing hub profile lists (parseProfileList(java.lang.String) to supply the well-known named profiles.

Returns:
array of known hub profile factories

getDefaultProfileClasses

public static Class[] getDefaultProfileClasses()
Returns a copy of the default set of HubProfile classes used when a hub is run and the list of profiles is not set explicitly. Each element should be an implementation of HubProfile with a no-arg constructor.

Returns:
array of hub profile classes

setDefaultProfileClasses

public static void setDefaultProfileClasses(Class[] dfltProfileClasses)
Sets the default set of HubProfile classes.

Parameters:
dfltProfileClasses - array to be returned by getDefaultProfileClasses

parseProfileList

public static HubProfileFactory[] parseProfileList(String listTxt)
Parses a string representing a list of hub profiles. The result is an array of HubProfileFactories. The list is comma-separated, and each element may be either the name of a HubProfileFactory or the classname of a HubProfile implementation with a suitable no-arg constructor.

Parameters:
listTxt - comma-separated list
Returns:
array of hub profile factories
Throws:
IllegalArgumentException - if unknown

createDefaultProfiles

public static HubProfile[] createDefaultProfiles()
Returns an array of default Hub Profiles. This is the result of calling the no-arg constructor for each element of the result of getDefaultProfileClasses().

Returns:
array of hub profiles to use by default

runHub

public static Hub runHub(HubServiceMode hubMode,
                         HubProfile[] profiles)
                  throws IOException
Starts a SAMP hub with a given set of profiles. The returned hub is running (start has been called).

If the hub mode corresponds to one of the GUI options, one of two things will happen. An attempt will be made to install an icon in the "system tray"; if this is successful, the attached popup menu will provide options for displaying the hub window and for shutting it down. If no system tray is available, the hub window will be posted directly, and the hub will shut down when this window is closed. System tray functionality is only available when running under Java 1.6 or later, and when using a suitable display manager.

Parameters:
hubMode - hub mode
profiles - SAMP profiles to support; if null a default set will be used
Returns:
running hub
Throws:
IOException

runHub

public static Hub runHub(HubServiceMode hubMode)
                  throws IOException
Starts a SAMP hub with a default set of profiles. This convenience method invokes runHub(hubMode,null).

Parameters:
hubMode - hub mode
Returns:
running hub
Throws:
IOException
See Also:
runHub(HubServiceMode,HubProfile[])

runExternalHub

public static void runExternalHub(HubServiceMode hubMode,
                                  Class[] profileClasses)
                           throws IOException
Attempts to start a hub in a new JVM with a given set of profiles. The resulting hub can therefore outlast the lifetime of the current application. Because of the OS interaction required, it's hard to make this bulletproof, and it may fail without an exception, but we do our best.

Parameters:
hubMode - hub mode
profileClasses - classes which implement HubProfile and have a no-arg constructor, determining which profiles the hub will support; if null, the default set from the current JVM is used
Throws:
IOException
See Also:
checkExternalHubAvailability()

runExternalHub

public static void runExternalHub(HubServiceMode hubMode)
                           throws IOException
Attempts to run a hub in a new JVM with a default set of profiles. The default set is taken from that in this JVM. This convenience method invokes runExternalHub(hubMode,null).

Parameters:
hubMode - hub mode
Throws:
IOException
See Also:
runExternalHub(HubServiceMode,java.lang.Class[])

checkExternalHubAvailability

public static void checkExternalHubAvailability()
                                         throws IOException
Attempts to determine whether an external hub can be started using runExternalHub. If it can be determined that such an attempt would fail, this method will throw an exception with an informative message. This method succeeding is not a guarantee that an external hub can be started successfullly. The behaviour of this method is not expected to change over the lifetime of a given JVM.

Throws:
IOException

main

public static void main(String[] args)
Main method, which allows configuration of which profiles will run and configuration of those individual profiles. Use the -h flag for usage.


runMain

public static int runMain(String[] args)
                   throws IOException
Invoked by main. In case of a usage error, it returns a non-zero value, but does not call System.exit.

Parameters:
args - command-line argument array
Returns:
non-zero for error completion
Throws:
IOException


Copyright © 2008-2011 AstroGrid. All Rights Reserved.