Package 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

Fields
Modifier and Type
Field
Description
`static final String`
`LOCALHOST_PROP`
Property which can be used to set name used for localhost in server endpoints.

## Method Summary

Modifier and Type
Method
Description
`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 Details

### 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 Details

### 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`". For non-ASCII characters, UTF-8 encoding is used.

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. For non-ASCII characters, UTF-8 encoding is used.

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 "+". For non-ASCII characters, UTF-8 encoding is used.

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