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
    Property which can be used to set name used for localhost in server endpoints.
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    Checks that a given List is legal for use in a SAMP context.
    static void
    Checks that a given Map is legal for use in a SAMP context.
    static void
    Checks that a given object is legal for use in a SAMP context.
    static void
    Checks that a given String is legal for use in a SAMP context.
    static void
    Checks that a string is a legal URL.
    static boolean
    Returns the boolean value for a SAMP boolean string.
    static double
    Returns the double value for a SAMP float string.
    static int
    Returns the integer value for a SAMP int string.
    static long
    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
    Turns a File into a URL.
    static String
    formatObject(Object obj, int indent)
    Pretty-prints a SAMP object.
    static Object
    Parses JSON text to give a SAMP object.
    static String
    Returns a string denoting the local host to be used for communicating local server endpoints and so on.
    static String
    Returns a string giving the version of the SAMP standard which this software implements.
    static String
    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
    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
    Reverses URI-style character escaping (%xy) on a string.
    static String
    Performs URI-style character escaping (%xy) on a string.
    static File
    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:
  • 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:
    • 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:
    • 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:
    • 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