Class 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.
    • 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 a long 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.
      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.
      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.
      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.
      • 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 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
    • 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 a long 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 - if d 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 - if url 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 object
        indent - 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
        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 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". 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 java.lang.String uriDecode​(java.lang.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 java.lang.String uriEncode​(java.lang.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 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 serialize
        multiline - 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