Version 0.1

Date: 31 Jul 2008

Initial release (beta). Targets SAMP WD v1.0 (25 June 2008).

Version 0.2

Date: 19 Sep 2008

Code reorganisation and pluggable XML-RPC implementation:

The XML-RPC and Standard Profile-related parts of the library have been reorganised somewhat. A new package org.astrogrid.samp.xmlrpc ant its descendants now hold all the code which relates specifically to XML-RPC communications and the SAMP Standard Profile; the code in the other packages is profile-agnostic and handles only transport-independent aspects of the protocol. The xmlrpc package itself defines a pluggable interface for providing XML-RPC client and server functionality; two implementations are also provided, in the packages xmlrpc.apache and xmlrpc.internal. The Apache one is basically what was there in previous versions; the internal one is completely freestanding, and if this is used the Apache XML-RPC library is not required for operation.

GUI functionality added

There are more classes in the org.astrogrid.samp.gui package to facilitate high-level use of SAMP within GUI applications. ConnectorGui provides Actions suitable for insertion in a general SAMP control menu, and SendActionManager provides menus and Actions for sending particular messages.

New command snooper:

Logs received messages to the terminal. Useful for debugging.

Minor changes:

• Moved some GUI functionality from client.HubConnector to gui.ConnectorGui.
• HubClient privateKey member is now an Object not a String, for greater generality.
• RegInfo(String,String,String) constructor withdrawn.
• HubRunner class moved from package hub to xmlrpc.
• Several other more or less minor changes.

Version 0.2-1

Date: 25 Sep 2008

Bugfixes:

• Fixed a problem with XML-RPC implementation when running in presence of unexpected (not 1.2) version of Apache XML-RPC library.
• jsamp.xmlrpc.impl property now correctly propagated to JVM running external hub.
• Race condition in unit tests which sometimes gave false failures is fixed.
• Fixed threading problem in hubmonitor which meant that sometimes window did not appear.
• Some other minor items.

Version 0.3

Date: 9 Dec 2008

Major New Features:

• There is now an option for both hub and client GUI to keep track of and display messages which have been sent. HubRunner and HubMonitor GUIs by default now have tabs showing messages sent/received and their current status - see GUI Features section for some screenshots. To see this in action, start the HubRunner in (default) msg-gui mode and then run HubTester. Or just use the hub with your own SAMP clients. Note that this functionality incurs some overhead - if not used no such overhead is incurred.
• A new small GUI component is available which just shows the icons for all registered clients (like what used to appear in the bottom right corner of VODesktop windows).
• Facilities have been added for full logging of all XML or RPC communications in the hub or clients. See new xml-log and rpc-log options to -xmlrpc flags of command-line tools, and classes org.astrogrid.samp.xmlrpc.internal.*LoggingInternal*.
• Replace DefaultSendActionManager with other, more capable, SendActionManager subclasses. This makes it easy to handle the results from messages which have been sent, for instance by passing the information to the user graphically or in other ways.
• HubMonitor tool can now subscribe to messages other than administrative ones, like Snooper.
• MessageSender tool now pretty-prints response(s).

Backwards Compatibility:

There have been a number of changes since release 0.2 which are backwardly incompatible, so that source code using earlier versions of JSAMP will need to be adjusted. GUI-related functionality is most affected. This is because I'm still designing it, and some changes were required to accommodate new features etc; sorry. I hope that there will be fewer backwardly incompatible changes in the future as the library matures - but I'm not offering any guarantees just yet. Some of the more obvious changes are as follows:

• New class gui.GuiHubConnector now contains the Swing-related functionality which was previously in (its superclass) client.HubConnector, and also all the functionality from the now removed class gui.ConnectorGui.
• HubRunner and ConnectorGui APIs modified to permit use of various different hub implementations (with different graphical characteristics - see HubMode).

If there are things which used to work in a previous version and you can't see how to do it now, please contact me and I'll advise how to update.

Bugfixes:

• Fixed server error which sometimes resulted in failed reads, especially for long messages.
• Fixed error in handling CalcStorm -xmlrpc flag.

Other:

• Change return values of callAll and notifyAll hub methods as per agreed modifications to the standard at version 1.1. Affects hub and client API, implementation and test suite.
• Default XML-RPC implementation is now Internal rather than Apache.
• HubConnector now subscribes to samp.hub.disconnect MType.
• Improved performance of internal client when sending long messages.
• Add SampUtils.isSampChar() convenience method.
• Add public createTag method to HubConnector.
• Added test for long messages in HubTester.
• HubTester now tests nearly all legal SAMP string characters.
• ...And some other things not mentioned here.

Version 0.3-1

Date: 27 Mar 2009

Minor Enhancements:

• Add GuiHubConnector.createRegisterOrHubAction method, which registers if it can, else offers the user to start a hub. This may be the only button you need.
• Internal HTTP server now tolerates LF as well as the correct CRLF as HTTP request header line terminators, as recommended by HTTP 1.1 (RFC2616).
• Add convenience methods call and callAll to HubConnector - these allow you to make asynchronous calls so that the results are delivered as callbacks to supplied objects without having to worry about registering handlers and matching tags.
• Add createTargetSelector/createTargetAction methods to SendActionManager class. These give another way (button plus combo box) go allow users to trigger a send.
• Add comment to .samp lockfile noting that contact XML-RPC URL hostname is configurable.
• Cache home directory when first determined in SampUtil.

Backward Compatibility:

• Moved HTTP server implementation used by internal XML-RPC implementation into its own package, samp.httpd. Also added some utility classes in that package to facilitate serving dynamic resources and resources from the classpath. This is because having a simple self-contained HTTP server may be useful for client implementations doing SAMP-like things other than strictly communicating with the hub.
• ResultHandler and LogResultHandler classes moved from package gui to client.
• Changed SAMP protocol version to 1.11.

Bug Fixes:

• Fixed hub lockfile location bug for Windows at Java 1.4.
• Fix process handling bug which caused Windows XP external hub start to write incomplete lock file.

Version 1.0

Date: 5 Aug 2009

Though this version is numbered 1.0, it's not a giant leap ahead of the previous one (0.3-1). However, this is the first release since SAMP became an IVOA Recommendation, and this toolkit is believed to be fully compliant with that standard. The intention is that backwardly incompatible changes will be kept to a minimum following this release.

New functionality:

• New Bridge client added. This is a significant bit of infrastructure which allows clients on different hubs to interoperate.
• Added popup menus to GUI hub views which allow you to ping or forcibly disconnect registered clients.
• System property jsamp.server.port provided to allow selection of the default server port.
• System property jsamp.lockfile provided to support non-standard lockfile location.
• HubConnector now subscribes by default to new client.env.get MType.
• Added -clientname and -clientmeta flags to Snooper command-line tool.
• You can now set the samp.secret string for HubRunner if you don't want it chosen randomly.
• Add some more documentation pages: System Properties, Debugging Aids and Bridge.
• The help message now reports relevant system properties as well as other help info.

Changes to behaviour (note some of these may have backward compatibility issues):

• The default hostname for HTTP server etc (SampUtils.getLocalHost()) is now "127.0.0.1", not the DNS name; in certain network environments this works better than the alternatives, though it's less good for inter-machine communications. This default can be altered by setting the samp.hostname system property; it has two new special values "[hostname]" and "[hostnumber]".
• Icon URLs declared by test clients etc now use internal server references rather than links to external static resources. This means icons are not dependent on network availability.
• Clients forcibly disconnected by samp.hub.disconnect now don't try to re-autoconnect themselves.
• Remove warning if permission change on .samp file to owner-only read fails. This permission change is probably not possible on Windows-like OSes (unless anyone can tell me different), and the warning causes confusion.
• System property samp.localhost renamed to jsamp.localhost (the old name is still recognised for backward compatibility).
• Withdraw -xmlrpc flag from command-line tools; the jsamp.xmlrpc.impl system property should be used instead.
• Standard version is now reported as v1.11 REC 2009-04-21.

API Changes (note some of these may have backward compatibility issues):

• Added DefaultClientProfile class; this is now the recommended way of getting a general purpose ClientProfile object (rather than using StandardClientProfile.getInstance(). Using this will aid pluggability (ability to use with non-standard profiles in the future).
• Added UtilServer class; this can help to reduce the number of HTTP servers run by a JSAMP application, and provides convenience methods for exporting local (e.g. file: or classpath) URLs.
• Added getHubClient and disconnect methods to BasicHubService; you can now use the hub object to forcibly disconnect clients.
• StandardClientProfile now has overridable getLockInfo method for better customisability.
• Added parseValue utility method to SampUtils class.
• Added new method HubConnector.connectionChanged.
• InternalServerFactory now returns a server which can be safely reused.
• Class LockInfo moved from org.astrogrid.samp package to org.astrogrid.samp.xmlrpc, which is where it should have been.

Bugfixes:

• Missing jsamp.version file now included in source zip archive.
• Fixed error reporting bug in messagesender tool.

Version 1.1

Date: 21 Jul 2010

Protocol extension:

• The environment variable SAMP_HUB can now be used to specify a non-default lockfile location for clients and hub to use with the Standard Profile. This usage is expected to be part of the next version of the SAMP standard (SAMP 1.2, in WD at time of writing). See the documentation for the StandardClientProfile class for details, and DefaultClientProfile for a JSAMP-specific extension to this mechanism. The non-standard jsamp.lockfile and jsamp.profile system properties which did the same job in a non-standard way have been withdrawn. This has some backwardly incompatible consequences:
  • jsamp.lockfile and jsamp.profile system properties withdrawn; use SAMP_HUB environment variable instead.
  • SampUtils.LOCKFILE_NAME constant withdrawn; use StandardClientProfile.LOCKFILE_NAME instead.
  • SampUtils.getLockFile() method withdrawn; use StandardClientProfile.getLockUrl() instead. If you want to find out if a hub is running, instead of SampUtils.getLockFile().exists(), use DefaultClientProfile.getProfile().isHubRunning().
  • LockInfo.readLockFile(File) method withdrawn; use LockInfo.readLockFile(URL) instead.
  • LockInfo.readLockFile() method withdrawn; use StandardClientProfile.getLockInfo() instead.
  • LockWriter no-arg constructor withdrawn.

Enhancements:

• Where possible, if the hub is running in GUI mode it will now install itself as an icon in the "system tray" rather than posting the window directly; a popup menu associated with the tray icon allows window display and hub shutdown. If the platform does not provide system tray functionality, it will revert to the previous behaviour of posting the window directly. System tray functionality is available only when running under Java 1.6 or later, and only when using a suitable display manager.
• Added -httplock flag to hubrunner, which allows publication of lockfile by HTTP for use by non-localhost clients.

Usability:

• Invoking JSamp class (e.g. "java -jar jsamp.jar") with no arguments now starts the hub rather than just printing a usage message.
• ClientProfile interface has new method isHubRunning. This is more general (and easier to use) than testing something like StandardClientProfile.getLockFile().exists().
• HubRunnner.runHub method now returns the running HubRunner instance.

Bugfixes:

• Fix error in XML-RPC fault responses (faultCode was string instead of int).
• Fix the MessageTracker hub so it doesn't get confused if clients re-use the same tag for different messages.
• Adjusted logic of client tracking in HubConnector to be more robust.
• Fix bug in outgoing message tooltips for MessageTracker message box.
• Fix concurrency issue in HttpServer.
• Fix issue which could cause GUI freeze while waiting for remote icons to load.
• Catch security exceptions when calling addShutdownHook in XmlRpcHubConnection. It seems that signed applets may not have the appropiate permissions.

Minor improvements:

• Command-line tools now use DefaultClientProfile.getProfile() rather than StandardClientProfile.getInstance() as they should (hence will be correctly influenced by SAMP_HUB environment variable).
• More tests added to HubTester for correctness of XML-RPC responses.
• Be more frugal with DocumentBuilderFactory instances to reduce some unwanted logging.
• Improve wait implementation in HubTester to avoid non-yield race conditions.
• A warning is now issued if getClientMap is called before declareSubscriptions on a HubConnector, since without declaring subscriptions the client map won't work.

Version 1.2

Date: 15 Feb 2011

The two main changes at this release are generalisation of the hub running framework to allow multiple profiles to run interfacing to the same hub simultaneously, and implementation of the experimental Web Profile. The former was motivated by the latter (though should really have been present from the start). This work was suggested by Jonathan Fay and financially supported by Microsoft Research, whose support is gratefully acknowledged. There are also a number of bug fixes and minor enhancements.

Hub framework:

The org.astrogrid.samp.hub.HubRunner class has been deprecated in favour of the new class org.astrogrid.samp.hub.Hub. This can be used from the command line or programmatically to start a hub, and it can run zero or more profiles, defined by the new HubProfile interface, simultaneously. HubProfile implementations are provided for the Standard Profile and the Web Profile, and you can plug in your own at runtime. This class is now the Main-Class defined in the jar file's Manifest, so invoking (e.g. clicking or java -jar) the jsamp-*.jar file will now invoke this class. Documentation of the command-line usage is on the Command-line Tools page. By default only the Standard Profile is run, so simply invoking the jar file will have much the same behaviour as it did in previous versions, that is starting a Standard Profile-only hub. Which profiles are run can be influenced in various ways, including by defining the jsamp.hub.profiles system property.

A new "facade" mode of hub operation has been introduced, which allows tunnelling from one hub profile to another (mostly of interest to hub profile implementors).

There have been a number of other backwardly incompatible changes to the hub implementation classes: Most of the HubService interface has been replaced using HubConnection and Receiver has been replaced with CallableClient, reducing amount and duplication of code, and some assumptions specific to the Standard Profile have been removed from the interfaces of hub classes which are properly profile-independent. These changes are not believed likely to affect anybody who is not writing hub implementation code.

Web Profile:

This release also includes client and hub implementations of the experimental Web Profile. Implementation is in the new package org.astrogrid.samp.web. Note that this profile is still under discussion and details of the definition may change in the future.

Bug fixes:

• Fixed URI escaping bugs related to "+" characters (new utility methods SampUtils.uriEncode/Decode).
• Fixed some concurrency bugs to do with handler lists in HubConnector, HttpServer, InternalServer and ApacheServer (thanks to Laurent Bourgès).
• Fixed, I think, threading issues that occasionally prevented hub forced shutdown notifications getting to some clients. It is possible this fix will have knock-on performance or other effects, especially in the presence of badly-behaved clients - please report if you notice problems. Thanks (again) to Laurent Borgès for extensive help with this.
• Fixed a bug related to output capture when an external hub is started.
• Fixed some not-quite-correct internal HTTP server error responses (405, 400).
• Fixed internal HTTP server so it won't reorder request/response headers.
• Improved header handling (case-sensitive, duplicated keys) in HttpServer.
• Fixed client XML logging bug.

Minor changes and enhancements:

• Changed pluggable XML-RPC implementation framework API slightly - handleCall method in SampXmlRpcHandler interface gets an additional argument.
• SAMP Version now declares itself as SAMP v1.2 REC.
• Some additional system properties are now propagated when starting an external hub.
• Window positioning now follows platform norms by default rather than the java policy of placement at (0,0). Specifically: the java.awt.Window.locationByPlatform system property is set, if it does not already have an explicit value, in the JSamp class.
• AbstractMessageHandler has a new method createResponse which may be overridden for more flexibility.
• External hub start action is disabled in JNLP context, since it won't work.

Version 1.3

Date: 2 Aug 2011

Various changes relating to configurable use of profiles and the Web Profile in particular, to match the SAMP 1.3 WD, and to enable experimentation with multi-profile configurations while we gain experience with security options. There is more discussion in the new Profiles page, but the main changes are:

• The Web Profile is now available, but not switched on, by default. The Web Profile (and other profiles) can be switched on or off while the hub is running by using the new Profiles menu in the hub window or system tray icon. There is a corresponding new hub command flag -web:extraprofiles and system property jsamp.hub.profiles.extra.
• The Profiles menu also has a Web Profile Configuration submenu, which allows fine control over the way the Web Profile is run. This is to permit experimentation with security options; this menu or some of its options may be withdrawn in future versions. There are corresponding flags for the hub command: -web:[no]cors, -web:[no]flash, -web:[no]silverlight, -web:[no]urlcontrol.
• The Web Profile hub server now blocks non-localhost requests at the HTTP level. This should benefit security.
• The Web Profile URL translation service now by default blocks access to sensitive resources (local filesystem and localhost URLs) if they have not previously been mentioned by a non-Web Profile client. This should benefit security.
• Web profile now uses a map argument and not a string argument to register(), as per the change to the Web Profile specification.
• Various related changes to the hub implementation and API have been made to enable the above. The recommended entry point, Hub.runHub(), still works though.

The Hub GUI window now has menus:

• File menu, which just allows hub shutdown.
• Clients menu, which allows pinging and disconnection of clients (this functionality duplicates the existing, but not very obvious, client popup menu).
• Profiles menu, as described above.

JSON is now used as the standard serialization/deserialization format for SAMP objects in a few places:

• New utility methods toJson and fromJson in SampUtils class.
• Non-scalar message parameter contents and client metadata can now be specified to the messagesender and snooper tools on the command line using JSON syntax.
• Message display, e.g. in the hub message tracker GUI, are now shown in JSON format. In practice this means you'll see a few more double quotes - it also means they can be cut and pasted directly into other JSON-aware contexts.

Other items:

• The ClientProfile.isHubRunning method now probes more agressively for a hub (for instance in the Standard Profile it pings rather than just looking for the .samp file). This is a change to both the API and the implementations.
• The Web Profile registration dialogue is now somewhat internationalised. Thanks to Luigi Paioro and Markus Demleitner for providing translations. This can be extended by providing further instances of AuthResourceBundle class or supplying a suitable org.astrogrid.samp.web.AuthResourceBundle_xx.properties resource; run AuthResourceBundle.main() for example output.
• The Web Profile hub now fails at start time rather than during registration attempts if Swing client authorization is in use with headless graphics.
• More helpful warning message when standard profile lockfile is present but broken (suggests deleting file).
• HubMonitor now correctly uses DefaultClientProfile rather than StandardClientProfile.

Version 1.3-1

Date: 26 Oct 2011

• Hub now runs with Web Profile on by default.
• Web Profile has a new configuration option, which restricts permitted MTypes that a Web Profile client can send. This is switched on by default.
• Tone down warning in the Web SAMP confirmation dialogue slightly to reflect improved security measures in default Web Profile configuration.
• The messagesender command-line tool has new flags -targetname and -targetid which replace the previous -target flag.
• Add French translation for Web SAMP confirmation dialogue (thanks to Thomas Boch).
• URL encode argument of ResourceHandler.addResource (thanks to Omar Laurino).
• Add -web:auth extreme mode to hub.
• Web hub profile now throws SampException not SecurityException on registration failure; this makes failures less verbose in the hub.

Version 1.3-2

Date: 12 Dec 2011

• Remove some code which was not compatible with J2S1.4.
• Web Profile URL control now controls all URLs not just local ones. All maps passing through the hub connection are now scanned for URLs.
• Reduce logging for message send failures, partly by reducing failures themselves.
• Hub implements x-samp.query.by-meta MType.
• New methods on Hub class to determine whether the hub is running and with what profiles.
• Added -subs flag to Snooper tool.
• Fixed bug in JSON parser (wouldn't recognise empty objects "{}").
• The implementation of MType restrictions for Web Profile clients has been changed. Blocked MTypes are now completely hidden from Web Profile clients. There is still a list of blocked MTypes (ones with known harmless semantics), but subscribing clients may override this, i.e. note MTypes that they subscribe to as known to be either harmless or harmful by annotating the subscription (populating the map value corresponding to the MType key) with a key "x-samp.mostly-harmless" and a value of "1" (harmless) or "0" (harmful).
• The Web Profile registration dialogue now reports the apparent URL of the registering client (as determined from the Referer header) if available.

Version 1.3-3

Date: 30 Oct 2012

• Failure to start some profiles no longer prevents the hub from starting up at all. This means that default configuration (Standard + Web profile) hub startup no longer fails on a machine that already has a web profile hub running on it.
• Reported standard version is now 1.3 REC.
• Fixed some broken command-line hub options (-[no]restrictmtypes and -[no]urlcontrol).
• Command line -web:* and -std:* flags are now used even when -profiles flag is not supplied explicitly (where possible).
• Added Hub.getRunningHubs static method to locate hubs running in current JVM, as requested by JMMC.
• Added Hub.getWindow() method, as requested by JMMC.
• Improved shutdown sequence, shutting down clients first and then hubs, following contribution from JMMC.
• Plugged several resource leaks (cancel auxiliary threads in HubConnector on setActive(false), free XML-RPC servers associated with callable clients on unregister) following contribution from JMMC.
• The distributed jar file is now signed with a Thawte code-signing certificate (owned by the University of Bristol). This means that you can provide a JNLP file to start a hub using WebStart which will not complain to the user about not being able to authenticate the publisher's identity.

Version 1.3-4

Date: 9 Oct 2013

• JSAMP has been rehosted, and no longer lives on AstroGrid sites. The distribution web site is now at http://www.star.bristol.ac.uk/~mbt/jsamp/, and the source can be found on github at https://github.com/mbtaylor/jsamp.
• Fixed the Web Profile hub to work with HTTPS-based web pages as well as HTTP-based ones; previously HTTPS pages were blocked for no good reason(?). Developers of applications which may run the JSAMP hub are encouraged to upgrade to this version to avoid penalising use of HTTPS in third-party SAMP web applications. Note added later: the HTTPS problem is not so easily solved.
• Add new system property jsamp.web.extrahosts to allow trusted non-local hosts to register with the Web Profile (for instance near-local mobile devices).
• Improve shutdown behaviour somewhat, now less prone to fail to delete .samp file in JNLP shutdown.
• The jar file is now distributed in both signed and unsigned forms.

Version 1.3.5

Date: 13 Nov 2014

• The build is now done using Maven 3. Thanks to Paul Harrison for doing most of the work on this. As a consequence, the version numbering system has changed - it's now a.b.c instead of a.b-c. Note although the POM file is updated etc, the release is not currently deploying to a central maven repository; I haven't worked out how to do that yet. If somebody out there is keen to see that happen and wants to help me out, get in touch.
• The jar file now contains "Permissions" and "Application-Name" attributes, which are required when running the hub as a signed jar under WebStart at java 7u51+.
• The Web Profile security dialogue has been adjusted so that long strings transmitted as application Name, Origin or URL do not extend the width of the popup window indefinitely.
• Updated Standard Profile samp.profile.version value to 1.3. By an oversight it had got stuck at 1.11.
• The hub now completes client calls without waiting for HTTP responses. (XmlRpcCallableClient implementation uses callAndForget instead of callAndWait). This prevents some cases of calls hanging in the presence of badly-behaved clients. Some other bugfixes related to hub shutdown were required to prevent this causing knock-on problems.
• Work round a JNLP shutdown classloading bug.
• One or two minor bugfixes.

Version 1.3.6

Date: 19 Sep 2019

• New command SampLoad, intended for use as browser helper application.
• Deprecate UtilServer.exportResource(String) in favour of exportResource(URL), on the grounds that it's easy to end up using the wrong classloader.
• Fix a javadoc error in SelectiveClientListModel.
• Fix a bug in SendActionManager that meant the targeted send action didn't do anything.
• Add HubConnector.isActive method.
• Downgrade internal HTTP server 404 logging messages from WARNING to INFO, so they are generally no longer visible to users.
• Fix SampUtil.fileToUrl to cope with non-URL-safe characters in filenames (UTF-8 encoding is used).
• Various changes to the code to facilitate implementation of the (experimental, not included here) TLS profile. These mostly involve publicising previously private methods, but there are a few changes to the client authorization for the Web Profile, including a backwardly-incompatible change to signature of the web.ClientAuthorizer.authorize method. Library users are not expected to notice these changes.

Version 1.3.7

Date: 18 Nov 2019

• Relax Origin restrictions in CORS web server to allow e.g. browser extensions.
• jsamp.notray system property introduced to prevent the hub appearing in the System Tray.

Version 1.3.8

Date: 13 Mar 2024

• Support keys defined by the Private Network Access proposal in hub Web Profile CORS pre-flight requests. At time of writing this prevents some warnings when using Web SAMP from Google Chrome; in future it may avoid browser blocking of Web SAMP communications.
• A signed jar file may no longer be available at this release.