Class SampUtils
- java.lang.Object
-
- org.astrogrid.samp.SampUtils
-
public class SampUtils extends java.lang.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 java.lang.String
LOCALHOST_PROP
Property which can be used to set name used for localhost in server endpoints.private static java.io.File
lockFile_
private static java.util.logging.Logger
logger_
private static java.lang.String
NEWLINE
private static java.lang.String
sampVersion_
private static java.lang.String
softwareVersion_
-
Constructor Summary
Constructors Modifier Constructor Description private
SampUtils()
Private constructor prevents instantiation.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
checkList(java.util.List list)
Checks that a given List is legal for use in a SAMP context.static void
checkMap(java.util.Map map)
Checks that a given Map is legal for use in a SAMP context.static void
checkObject(java.lang.Object obj)
Checks that a given object is legal for use in a SAMP context.static void
checkString(java.lang.String string)
Checks that a given String is legal for use in a SAMP context.static void
checkUrl(java.lang.String url)
Checks that a string is a legal URL.static boolean
decodeBoolean(java.lang.String s)
Returns the boolean value for a SAMP boolean string.static double
decodeFloat(java.lang.String s)
Returns the double value for a SAMP float string.static int
decodeInt(java.lang.String s)
Returns the integer value for a SAMP int string.static long
decodeLong(java.lang.String s)
Returns the integer value as along
for a SAMP int string.static java.lang.String
encodeBoolean(boolean b)
Returns a SAMP boolean string representation of a boolean value.static java.lang.String
encodeFloat(double d)
Returns a SAMP float string representation of a floating point value.static java.lang.String
encodeInt(int i)
Returns a SAMP int string representation of an integer.static java.lang.String
encodeLong(long i)
Returns a SAMP int string representation of a long integer.static java.net.URL
fileToUrl(java.io.File file)
Turns a File into a URL.private static int
findAnyPort()
Locates an unused server port on the local host.static java.lang.String
formatObject(java.lang.Object obj, int indent)
Pretty-prints a SAMP object.static java.lang.Object
fromJson(java.lang.String str)
Parses JSON text to give a SAMP object.private static java.lang.String
getLineSeparator()
Returns the system-dependent line separator sequence.static java.lang.String
getLocalhost()
Returns a string denoting the local host to be used for communicating local server endpoints and so on.static java.lang.String
getSampVersion()
Returns a string giving the version of the SAMP standard which this software implements.static java.lang.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 java.lang.Object
parseValue(java.lang.String str)
Parses a command-line string as a SAMP object.private static java.lang.String
readResource(java.lang.String rname)
Returns the contents of a resource as a string.private static java.lang.String
replaceChar(java.lang.String in, char oldChar, java.lang.String newTxt)
Replaces all occurrences of a single character with a given replacement string.private static int
scanForPort(int startPort, int nTry)
Two problems with this one - it may be a bit inefficient, and there's an annoying bug in the Apache XML-RPC WebServer class which causes it to print "java.util.NoSuchElementException" to the server's System.err for every port scanned by this routine that an org.apache.xmlrpc.WebServer server is listening on.static java.lang.String
toJson(java.lang.Object item, boolean multiline)
Serializes a SAMP object to a JSON string.static java.lang.String
toString(Client client)
Returns a string representation of a client object.static java.lang.String
uriDecode(java.lang.String text)
Reverses URI-style character escaping (%xy) on a string.static java.lang.String
uriEncode(java.lang.String text)
Performs URI-style character escaping (%xy) on a string.static java.io.File
urlToFile(java.net.URL url)
Attempts to interpret a URL as a file.
-
-
-
Field Detail
-
LOCALHOST_PROP
public static final java.lang.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
-
logger_
private static final java.util.logging.Logger logger_
-
sampVersion_
private static java.lang.String sampVersion_
-
softwareVersion_
private static java.lang.String softwareVersion_
-
lockFile_
private static java.io.File lockFile_
-
NEWLINE
private static final java.lang.String NEWLINE
-
-
Method Detail
-
encodeInt
public static java.lang.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(java.lang.String s)
Returns the integer value for a SAMP int string.- Parameters:
s
- SAMP int string- Returns:
- integer value
- Throws:
java.lang.NumberFormatException
- if conversion fails
-
encodeLong
public static java.lang.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(java.lang.String s)
Returns the integer value as along
for a SAMP int string.- Parameters:
s
- SAMP int string- Returns:
- long integer value
- Throws:
java.lang.NumberFormatException
- if conversion fails
-
encodeFloat
public static java.lang.String encodeFloat(double d)
Returns a SAMP float string representation of a floating point value.- Parameters:
d
- double value- Returns:
- SAMP double string
- Throws:
java.lang.IllegalArgumentException
- ifd
is NaN or infinite
-
decodeFloat
public static double decodeFloat(java.lang.String s)
Returns the double value for a SAMP float string.- Parameters:
s
- SAMP float string- Returns:
- double value
- Throws:
java.lang.NumberFormatException
- if conversion fails
-
encodeBoolean
public static java.lang.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(java.lang.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(java.lang.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(java.util.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(java.util.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(java.lang.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(java.lang.String url)
Checks that a string is a legal URL.- Parameters:
url
- string to check- Throws:
DataException
- ifurl
is not a legal URL
-
toString
public static java.lang.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 java.lang.String formatObject(java.lang.Object obj, int indent)
Pretty-prints a SAMP object.- Parameters:
obj
- SAMP-friendly objectindent
- base indent for text block- Returns:
- string containing formatted object
-
parseValue
public static java.lang.Object parseValue(java.lang.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 java.lang.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
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 thanjsamp.localhost
. This name is still accepted for backwards compatibility.- Returns:
- local host name
-
getUnusedPort
public static int getUnusedPort(int startPort) throws java.io.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:
java.io.IOException
-
fileToUrl
public static java.net.URL fileToUrl(java.io.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 java.lang.String uriDecode(java.lang.String text)
Reverses URI-style character escaping (%xy) on a string. Note, unlikeURLDecoder
, this does not turn "+" characters into spaces.- Parameters:
text
- escaped text- Returns:
- unescaped text
- See Also:
- "RFC 2396, Section 2.4"
-
uriEncode
public static java.lang.String uriEncode(java.lang.String text)
Performs URI-style character escaping (%xy) on a string. Note, unlikeURLEncoder
, this encodes spaces as "%20" and not "+".- Parameters:
text
- unescaped text- Returns:
- escaped text
- See Also:
- "RFC 2396, Section 2.4"
-
urlToFile
public static java.io.File urlToFile(java.net.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 java.lang.Object fromJson(java.lang.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 java.lang.String toJson(java.lang.Object item, boolean multiline)
Serializes a SAMP object to a JSON string.- Parameters:
item
- to serializemultiline
- true for formatted multiline output, false for a single line
-
getSampVersion
public static java.lang.String getSampVersion()
Returns a string giving the version of the SAMP standard which this software implements.- Returns:
- SAMP standard version
-
getSoftwareVersion
public static java.lang.String getSoftwareVersion()
Returns a string giving the version of this software package.- Returns:
- JSAMP version
-
readResource
private static java.lang.String readResource(java.lang.String rname)
Returns the contents of a resource as a string.- Parameters:
rname
- resource name (in the sense ofClass.getResource(java.lang.String)
)
-
getLineSeparator
private static java.lang.String getLineSeparator()
Returns the system-dependent line separator sequence.- Returns:
- line separator
-
replaceChar
private static java.lang.String replaceChar(java.lang.String in, char oldChar, java.lang.String newTxt)
Replaces all occurrences of a single character with a given replacement string.- Parameters:
in
- input stringoldChar
- character to replacenewText
- replacement string- Returns:
- modified string
-
findAnyPort
private static int findAnyPort() throws java.io.IOException
Locates an unused server port on the local host. Potential problem: between when this method completes and when the return value of this method is used by its caller, it's possible that the port will get used by somebody else. Probably this will not happen much in practice??- Returns:
- unused server port
- Throws:
java.io.IOException
-
scanForPort
private static int scanForPort(int startPort, int nTry) throws java.io.IOException
Two problems with this one - it may be a bit inefficient, and there's an annoying bug in the Apache XML-RPC WebServer class which causes it to print "java.util.NoSuchElementException" to the server's System.err for every port scanned by this routine that an org.apache.xmlrpc.WebServer server is listening on.- Parameters:
startPort
- port to start scanning upwards fromnTry
- number of ports in sequence to try before admitting defeat- Returns:
- unused server port
- Throws:
java.io.IOException
-
-