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.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.
