Class Hub
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
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
System property name for supplying default profiles ("jsamp.hub.profiles.extra") additional to those inHUBPROFILES_PROP
which will be supported by the hub but switched off at hub startup time.static final String
System property name for supplying default profiles ("jsamp.hub.profiles") available at hub startup. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic void
Attempts to determine whether an external hub can be started usingrunExternalHub
.static HubProfile[]
createDefaultProfiles
(boolean extra) Returns an array of default Hub Profiles.static 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.Returns the hub service associated with this hub.static HubProfileFactory[]
Returns a standard list of known HubProfileFactories.static Hub[]
Returns an array of all the instances of this class which are currently running.Returns the hub profiles currently running on behalf of this hub.Returns a window for user monitoring and control of this hub, if available.static void
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, 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
Invoked by main.static void
setDefaultProfileClasses
(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.
-
Field Details
-
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 toparseProfileList(java.lang.String)
.- See Also:
-
EXTRAHUBPROFILES_PROP
System property name for supplying default profiles ("jsamp.hub.profiles.extra") additional to those inHUBPROFILES_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 toparseProfileList(java.lang.String)
.- See Also:
-
-
Constructor Details
-
Hub
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 Details
-
shutdown
public void shutdown()Stops this hub and its profiles running. -
startProfile
Starts a profile running on behalf of this hub.- Parameters:
profile
- to start- Throws:
IOException
-
stopProfile
Stops a profile running on behalf of this hub, and disconnects all clients registered with it.- Parameters:
profile
- profile to stop
-
getHubService
Returns the hub service associated with this hub.- Returns:
- hub service
-
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
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
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
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 ofHubProfile
with a no-arg constructor.- Parameters:
extra
- false for starting classes, true for additional ones- Returns:
- array of hub profile classes
-
setDefaultProfileClasses
Sets the default set of HubProfile classes.- Parameters:
clazzes
- array to be returned by getDefaultProfileClassesextra
- false for starting classes, true for additional ones
-
parseProfileList
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 thename
of a HubProfileFactory or the classname of aHubProfile
implementation with a suitable no-arg constructor.- Parameters:
listTxt
- comma-separated list- Returns:
- array of hub profile factories
- Throws:
IllegalArgumentException
- if unknown
-
createDefaultProfiles
Returns an array of default Hub Profiles. This is the result of calling the no-arg constructor for each element of the result ofgetDefaultProfileClasses(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 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 theextraProfiles
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 modeprofiles
- SAMP profiles to support on hub startup; if null a default set will be usedextraProfiles
- SAMP profiles to offer for later startup under user control; if null a default set will be used- Returns:
- running hub
- Throws:
IOException
-
runHub
Starts a SAMP hub with a default set of profiles. This convenience method invokesrunHub(hubMode,null,null)
.- Parameters:
hubMode
- hub mode- Returns:
- running hub
- Throws:
IOException
- See Also:
-
runExternalHub
public static void runExternalHub(HubServiceMode hubMode, Class[] profileClasses, Class[] extraProfileClasses) 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.The classes specified by the
profileClasses
andextraProfileClasses
arguments must implementHubProfile
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 modeprofileClasses
- hub profile classes to start on hub startupextraProfileClasses
- hub profile classes which may be started later under user control- Throws:
IOException
- See Also:
-
runExternalHub
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 invokesrunExternalHub(hubMode,null,null)
.- Parameters:
hubMode
- hub mode- Throws:
IOException
- See Also:
-
getRunningHubs
Returns an array of all the instances of this class which are currently running.- Returns:
- running hubs
-
checkExternalHubAvailability
Attempts to determine whether an external hub can be started usingrunExternalHub
. 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
Main method, which allows configuration of which profiles will run and configuration of those individual profiles. Use the-h
flag for usage. -
runMain
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
-