org.astrogrid.samp
Class SampUtils

java.lang.Object
  extended by 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:

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


Copyright © 2008-2011 AstroGrid. All Rights Reserved.