org.astrogrid.samp
Class SampUtils

java.lang.Object
  org.astrogrid.samp.SampUtils

public class SampUtils
extends Object

Contains static utility methods for use with the SAMP toolkit.

Since:

15 Jul 2008

Author:

Mark Taylor

Field Summary

static String

LOCALHOST_PROP Property which can be used to set name used for localhost in server endpoints.

Method Summary

static void	checkList(List list) Checks that a given List is legal for use in a SAMP context.
static void	checkMap(Map map) Checks that a given Map is legal for use in a SAMP context.
static void	checkObject(Object obj) Checks that a given object is legal for use in a SAMP context.
static void	checkString(String string) Checks that a given String is legal for use in a SAMP context.
static void	checkUrl(String url) Checks that a string is a legal URL.
static boolean	decodeBoolean(String s) Returns the boolean value for a SAMP boolean string.
static double	decodeFloat(String s) Returns the double value for a SAMP float string.
static int	decodeInt(String s) Returns the integer value for a SAMP int string.
static long	decodeLong(String s) Returns the integer value as a long for a SAMP int string.
static String	encodeBoolean(boolean b) Returns a SAMP boolean string representation of a boolean value.
static String	encodeFloat(double d) Returns a SAMP float string representation of a floating point value.
static String	encodeInt(int i) Returns a SAMP int string representation of an integer.
static String	encodeLong(long i) Returns a SAMP int string representation of a long integer.
static URL	fileToUrl(File file) Turns a File into a URL.
static String	formatObject(Object obj, int indent) Pretty-prints a SAMP object.
static Object	fromJson(String str) Parses JSON text to give a SAMP object.
static String	getLocalhost() Returns a string denoting the local host to be used for communicating local server endpoints and so on.
static String	getSampVersion() Returns a string giving the version of the SAMP standard which this software implements.
static String	getSoftwareVersion() Returns a string giving the version of this software package.
static int	getUnusedPort(int startPort) Returns an unused port number on the local host.
static boolean	isStringChar(char c) Indicates whether a given character is legal to include in a SAMP string.
static Object	parseValue(String str) Parses a command-line string as a SAMP object.
static String	toJson(Object item, boolean multiline) Serializes a SAMP object to a JSON string.
static String	toString(Client client) Returns a string representation of a client object.
static String	uriDecode(String text) Reverses URI-style character escaping (%xy) on a string.
static String	uriEncode(String text) Performs URI-style character escaping (%xy) on a string.
static File	urlToFile(URL url) Attempts to interpret a URL as a file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOCALHOST_PROP

public static final String LOCALHOST_PROP

Property which can be used to set name used for localhost in server endpoints. Value is "jsamp.localhost".

See Also:

getLocalhost(), Constant Field Values

Method Detail

encodeInt

public static String encodeInt(int i)

Returns a SAMP int string representation of an integer.

Parameters:

i - integer value

Returns:

SAMP int string

decodeInt

public static int decodeInt(String s)

Returns the integer value for a SAMP int string.

Parameters:

s - SAMP int string

Returns:

integer value

Throws:

NumberFormatException - if conversion fails

encodeLong

public static String encodeLong(long i)

Returns a SAMP int string representation of a long integer.

Parameters:

i - integer value

Returns:

SAMP int string

decodeLong

public static long decodeLong(String s)

Returns the integer value as a long for a SAMP int string.

Parameters:

s - SAMP int string

Returns:

long integer value

Throws:

NumberFormatException - if conversion fails

encodeFloat

public static String encodeFloat(double d)

Returns a SAMP float string representation of a floating point value.

Parameters:

d - double value

Returns:

SAMP double string

Throws:

IllegalArgumentException - if d is NaN or infinite

decodeFloat

public static double decodeFloat(String s)

Returns the double value for a SAMP float string.

Parameters:

s - SAMP float string

Returns:

double value

Throws:

NumberFormatException - if conversion fails

encodeBoolean

public static String encodeBoolean(boolean b)

Returns a SAMP boolean string representation of a boolean value.

Parameters:

b - boolean value

Returns:

SAMP boolean string

decodeBoolean

public static boolean decodeBoolean(String s)

Returns the boolean value for a SAMP boolean string.

Parameters:

s - SAMP boolean string

Returns:

false iff s is equal to zero

checkObject

public static void checkObject(Object obj)

Checks that a given object is legal for use in a SAMP context. This checks that it is either a String, List or Map, that any Map keys are Strings, and that Map values and List elements are themselves legal (recursively).

Parameters:

obj - object to check

Throws:

DataException - in case of an error

checkMap

public static void checkMap(Map map)

Checks that a given Map is legal for use in a SAMP context. All its keys must be strings, and its values must be legal SAMP objects.

Parameters:

map - map to check

Throws:

DataException - in case of an error

See Also:

checkObject(java.lang.Object)

checkList

public static void checkList(List list)

Checks that a given List is legal for use in a SAMP context. All its elements must be legal SAMP objects.

Parameters:

list - list to check

Throws:

DataException - in case of error

See Also:

checkObject(java.lang.Object)

checkString

public static void checkString(String string)

Checks that a given String is legal for use in a SAMP context. All its characters must be in the range 0x01 - 0x7f.

Parameters:

string - string to check

Throws:

DataException - in case of error

isStringChar

public static boolean isStringChar(char c)

Indicates whether a given character is legal to include in a SAMP string.

Returns:

true iff c is 0x09, 0x0a, 0x0d or 0x20--0x7f

checkUrl

public static void checkUrl(String url)

Checks that a string is a legal URL.

Parameters:

url - string to check

Throws:

DataException - if url is not a legal URL

toString

public static String toString(Client client)

Returns a string representation of a client object. The name is used if present, otherwise the ID.

Parameters:

client - client object

Returns:

string

formatObject

public static String formatObject(Object obj,
                                  int indent)

Pretty-prints a SAMP object.

Parameters:

obj - SAMP-friendly object

indent - base indent for text block

Returns:

string containing formatted object

parseValue

public static Object parseValue(String str)

Parses a command-line string as a SAMP object. If it can be parsed as a SAMP-friendly JSON string, that interpretation will be used. Otherwise, the value is just the string as presented.

Parameters:

str - command-line argument

Returns:

SAMP object

getLocalhost

public static String getLocalhost()

Returns a string denoting the local host to be used for communicating local server endpoints and so on.

The value returned by default is the loopback address, "127.0.0.1". However this behaviour can be overridden by setting the LOCALHOST_PROP system property to the string which should be returned instead. This may be necessary if the loopback address is not appropriate, for instance in the case of multiple configured loopback interfaces(?) or where SAMP communication is required across different machines. There are two special values which may be used for this property:

• [hostname]: uses the fully qualified domain name of the host
• [hostnumber]: uses the IP number of the host

If these determinations fail for some reason, a fallback value of 127.0.0.1 will be used.

In JSAMP version 0.3-1 and prior versions, the [hostname] behaviour was the default. Although this might be seen as more correct, in practice it could cause a lot of problems with DNS configurations which are incorrect or unstable (common in laptops outside their usual networks). See, for instance, AstroGrid bugzilla tickets 1799, 2151.

In JSAMP version 0.3-1 and prior versions, the property was named samp.localhost rather than jsamp.localhost. This name is still accepted for backwards compatibility.

Returns:

local host name

getUnusedPort

public static int getUnusedPort(int startPort)
                         throws IOException

Returns an unused port number on the local host.

Parameters:

startPort - suggested port number; may or may not be used

Returns:

unused port

Throws:

IOException

fileToUrl

public static URL fileToUrl(File file)

Turns a File into a URL. Unlike Sun's J2SE, this gives you a URL which conforms to RFC1738 and looks like "file://localhost/abs-path" rather than "file:abs-or-rel-path".

Parameters:

file - file

Returns:

URL

See Also:

"RFC 1738", Sun Java bug 6356783

uriDecode

public static String uriDecode(String text)

Reverses URI-style character escaping (%xy) on a string. Note, unlike URLDecoder, this does not turn "+" characters into spaces.

Parameters:

text - escaped text

Returns:

unescaped text

See Also:

"RFC 2396, Section 2.4"

uriEncode

public static String uriEncode(String text)

Performs URI-style character escaping (%xy) on a string. Note, unlike URLEncoder, this encodes spaces as "%20" and not "+".

Parameters:

text - unescaped text

Returns:

escaped text

See Also:

"RFC 2396, Section 2.4"

urlToFile

public static File urlToFile(URL url)

Attempts to interpret a URL as a file. If the URL does not have the "file:" protocol, null is returned.

Parameters:

url - URL, may or may not be file: protocol

Returns:

file, or null

fromJson

public static Object fromJson(String str)

Parses JSON text to give a SAMP object. Note that double-quoted strings are the only legal scalars (no unquoted numbers or booleans).

Parameters:

str - string to parse

Returns:

SAMP object

toJson

public static String toJson(Object item,
                            boolean multiline)

Serializes a SAMP object to a JSON string.

Parameters:

item - to serialize

multiline - true for formatted multiline output, false for a single line

getSampVersion

public static String getSampVersion()

Returns a string giving the version of the SAMP standard which this software implements.

Returns:

SAMP standard version

getSoftwareVersion

public static String getSoftwareVersion()

Returns a string giving the version of this software package.

Returns:

JSAMP version