Class Hub


  • public class Hub
    extends java.lang.Object
    Class which manages 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[], boolean) method or externally by using the "jsamp.hub.profiles" and "jsamp.hub.profiles.extra" system properties. 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, Sylvain Lafrasse
    • Constructor Summary

      Constructors 
      Constructor Description
      Hub​(HubService service)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void checkExternalHubAvailability()
      Attempts to determine whether an external hub can be started using runExternalHub.
      private static java.lang.Class[] createDefaultProfileClasses​(boolean extra)
      Invoked at class load time to come up with the list of hub profiles to use when no profiles are specified explicitly.
      static HubProfile[] createDefaultProfiles​(boolean extra)
      Returns an array of default Hub Profiles.
      private static void discardBytes​(java.io.InputStream in)
      Ensures that any bytes from a given input stream are discarded.
      private static void execBackground​(java.lang.String[] cmdarray)
      Executes a command in a separate process, and discards any stdout or stderr output generated by it.
      static java.lang.Class[] getDefaultProfileClasses​(boolean extra)
      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.
      HubService getHubService()
      Returns the hub service associated with this hub.
      static HubProfileFactory[] getKnownHubProfileFactories()
      Returns a standard list of known HubProfileFactories.
      private static HubProfile[] getProfiles​(java.lang.String profTxt, java.util.List argList, boolean isExtra, java.lang.String usage)
      Parses profile list command-line argument and associated command-line arguments to construct a list of required profiles.
      static Hub[] getRunningHubs()
      Returns an array of all the instances of this class which are currently running.
      HubProfile[] getRunningProfiles()
      Returns the hub profiles currently running on behalf of this hub.
      javax.swing.JFrame getWindow()
      Returns a window for user monitoring and control of this hub, if available.
      static void main​(java.lang.String[] args)
      Main method, which allows configuration of which profiles will run and configuration of those individual profiles.
      private static HubProfileFactory parseProfileClass​(java.lang.String txt)
      Parses a string representing a hub profile.
      static HubProfileFactory[] parseProfileList​(java.lang.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, java.lang.Class[] profileClasses, java.lang.Class[] extraProfileClasses)
      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, HubProfile[] extraProfiles)
      Starts a SAMP hub with given sets of profiles.
      static int runMain​(java.lang.String[] args)
      Invoked by main.
      static void setDefaultProfileClasses​(java.lang.Class[] clazzes, boolean extra)
      Sets the default set of HubProfile classes.
      void shutdown()
      Stops this hub and its profiles running.
      void startProfile​(HubProfile profile)
      Starts a profile running on behalf of this hub.
      void stopProfile​(HubProfile profile)
      Stops a profile running on behalf of this hub, and disconnects all clients registered with it.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • profileList_

        private final java.util.List profileList_
      • defaultDefaultProfileClasses_

        private static java.lang.Class[] defaultDefaultProfileClasses_
      • defaultDefaultExtraProfileClasses_

        private static java.lang.Class[] defaultDefaultExtraProfileClasses_
      • defaultProfileClasses_

        private static java.lang.Class[] defaultProfileClasses_
      • defaultExtraProfileClasses_

        private static java.lang.Class[] defaultExtraProfileClasses_
      • hubList_

        private static final java.util.Map hubList_
      • logger_

        private static final java.util.logging.Logger logger_
      • HUBPROFILES_PROP

        public static final java.lang.String HUBPROFILES_PROP
        System property name for supplying default profiles ("jsamp.hub.profiles") available at hub startup. The value of this property, if any, will be fed to parseProfileList(java.lang.String).
        See Also:
        Constant Field Values
      • EXTRAHUBPROFILES_PROP

        public static final java.lang.String EXTRAHUBPROFILES_PROP
        System property name for supplying default profiles ("jsamp.hub.profiles.extra") additional to those in HUBPROFILES_PROP which will be supported by the hub but switched off at hub startup time. 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)
        Constructor. Note that this object does not start the service, it must be started explicitly, either before or after this constructor is called.
        Parameters:
        service - hub service
    • Method Detail

      • shutdown

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

        public void startProfile​(HubProfile profile)
                          throws java.io.IOException
        Starts a profile running on behalf of this hub.
        Parameters:
        profile - to start
        Throws:
        java.io.IOException
      • stopProfile

        public void stopProfile​(HubProfile profile)
        Stops a profile running on behalf of this hub, and disconnects all clients registered with it.
        Parameters:
        profile - profile to stop
      • getHubService

        public HubService getHubService()
        Returns the hub service associated with this hub.
        Returns:
        hub service
      • getRunningProfiles

        public HubProfile[] getRunningProfiles()
        Returns the hub profiles currently running on behalf of this hub.
        Returns:
        profiles that have been started and not yet stopped by this hub
      • getWindow

        public javax.swing.JFrame getWindow()
        Returns a window for user monitoring and control of this hub, if available. The default implementation returns null, but this may be overridden depending on how this hub was instantiated.
        Returns:
        hub monitor/control window, or null
      • 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 java.lang.Class[] getDefaultProfileClasses​(boolean extra)
        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.
        Parameters:
        extra - false for starting classes, true for additional ones
        Returns:
        array of hub profile classes
      • setDefaultProfileClasses

        public static void setDefaultProfileClasses​(java.lang.Class[] clazzes,
                                                    boolean extra)
        Sets the default set of HubProfile classes.
        Parameters:
        clazzes - array to be returned by getDefaultProfileClasses
        extra - false for starting classes, true for additional ones
      • createDefaultProfileClasses

        private static java.lang.Class[] createDefaultProfileClasses​(boolean extra)
        Invoked at class load time to come up with the list of hub profiles to use when no profiles are specified explicitly. By default this is just the standard profile, but if the HUBPROFILES_PROP system property is defined its value is used instead.
        Parameters:
        extra - false for starting classes, true for additional ones
        Returns:
        default array of hub profile classes
      • parseProfileList

        public static HubProfileFactory[] parseProfileList​(java.lang.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:
        java.lang.IllegalArgumentException - if unknown
      • parseProfileClass

        private static HubProfileFactory parseProfileClass​(java.lang.String txt)
        Parses a string representing a hub profile. Each element may be either the name of a HubProfileFactory or the classname of a HubProfile implementation with a suitable no-arg constructor.
        Parameters:
        txt - string
        Returns:
        hub profile factory
        Throws:
        java.lang.IllegalArgumentException - if unknown
      • createDefaultProfiles

        public static HubProfile[] createDefaultProfiles​(boolean extra)
        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(boolean).
        Parameters:
        extra - false for starting profiles, true for additional ones
        Returns:
        array of hub profiles to use by default
      • runHub

        public static Hub runHub​(HubServiceMode hubMode,
                                 HubProfile[] profiles,
                                 HubProfile[] extraProfiles)
                          throws java.io.IOException
        Starts a SAMP hub with given sets of profiles. The returned hub is running.

        The profiles argument gives the profiles which will be started initially, and the extraProfiles argument lists more that can be started under user control later. If either or both list is given as null, suitable defaults will be used.

        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 on hub startup; if null a default set will be used
        extraProfiles - SAMP profiles to offer for later startup under user control; if null a default set will be used
        Returns:
        running hub
        Throws:
        java.io.IOException
      • runHub

        public static Hub runHub​(HubServiceMode hubMode)
                          throws java.io.IOException
        Starts a SAMP hub with a default set of profiles. This convenience method invokes runHub(hubMode,null,null).
        Parameters:
        hubMode - hub mode
        Returns:
        running hub
        Throws:
        java.io.IOException
        See Also:
        runHub(HubServiceMode,HubProfile[],HubProfile[])
      • runExternalHub

        public static void runExternalHub​(HubServiceMode hubMode,
                                          java.lang.Class[] profileClasses,
                                          java.lang.Class[] extraProfileClasses)
                                   throws java.io.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.

        The classes specified by the profileClasses and extraProfileClasses arguments must implement HubProfile and must have a no-arg constructor. If null is given in either case suitable defaults, taken from the current JVM, are used.

        Parameters:
        hubMode - hub mode
        profileClasses - hub profile classes to start on hub startup
        extraProfileClasses - hub profile classes which may be started later under user control
        Throws:
        java.io.IOException
        See Also:
        checkExternalHubAvailability()
      • runExternalHub

        public static void runExternalHub​(HubServiceMode hubMode)
                                   throws java.io.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,null).
        Parameters:
        hubMode - hub mode
        Throws:
        java.io.IOException
        See Also:
        runExternalHub(HubServiceMode,java.lang.Class[],java.lang.Class[])
      • getRunningHubs

        public static Hub[] getRunningHubs()
        Returns an array of all the instances of this class which are currently running.
        Returns:
        running hubs
      • checkExternalHubAvailability

        public static void checkExternalHubAvailability()
                                                 throws java.io.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:
        java.io.IOException
      • main

        public static void main​(java.lang.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​(java.lang.String[] args)
                           throws java.io.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:
        java.io.IOException
      • getProfiles

        private static HubProfile[] getProfiles​(java.lang.String profTxt,
                                                java.util.List argList,
                                                boolean isExtra,
                                                java.lang.String usage)
                                         throws java.io.IOException
        Parses profile list command-line argument and associated command-line arguments to construct a list of required profiles. If there is an argument processing error, an error message will be written to standard error and a null value will be returned.
        Parameters:
        profTxt - string value of profiles parameter (may be null)
        argList - complete list of other so far unused command line args
        isExtra - true for extraProfiles, false for main ones
        usage - profile flag usage string, used for error messages
        Returns:
        profiles array, or null
        Throws:
        java.io.IOException
      • execBackground

        private static void execBackground​(java.lang.String[] cmdarray)
                                    throws java.io.IOException
        Executes a command in a separate process, and discards any stdout or stderr output generated by it. Simply calling Runtime.exec can block the process until its output is consumed.
        Parameters:
        cmdarray - array containing the command to call and its args
        Throws:
        java.io.IOException
      • discardBytes

        private static void discardBytes​(java.io.InputStream in)
        Ensures that any bytes from a given input stream are discarded.
        Parameters:
        in - input stream