Package com.stata.sfi

Class SFIToolkit

  • public final class SFIToolkit
extends Object
    This class provides a set of core tools for interacting with Stata.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void callGC()
      Call the Java garbage collector. Calling this method should generally be avoided.
      static void display​(Object o)
      Display an object in the Stata Results window.
      static void display​(Object o, boolean asis)
      Display an object in the Stata Results window.
      static void display​(Object o, DisplayMode mode)
      Display an object in the Stata Results window.
      static void display​(Object o, DisplayMode mode, boolean asis)
      Display an object in the Stata Results window.
      static void display​(String s)
      Display a string in the Stata Results window.
      static void display​(String s, boolean asis)
      Display a string in the Stata Results window.
      static void display​(String s, DisplayMode mode)
      Display a string in the Stata Results window.
      static void display​(String s, DisplayMode mode, boolean asis)
      Display a string in the Stata Results window.
      static void displayln()
      Send a line separator to the output.
      static void displayln​(Object o)
      Display an object in the Stata Results window and automatically add a line separator at the end.
      static void displayln​(Object o, boolean asis)
      Display an object in the Stata Results window and automatically add a line separator at the end.
      static void displayln​(Object o, DisplayMode mode)
      Display an object in the Stata Results window and automatically add a line separator at the end.
      static void displayln​(Object o, DisplayMode mode, boolean asis)
      Display an object in the Stata Results window and automatically add a line separator at the end.
      static void displayln​(String s)
      Display a string in the Stata Results window and automatically add a line separator at the end.
      static void displayln​(String s, DisplayMode mode)
      Display a string in the Stata Results window and automatically add a line separator at the end.
      static void displayln​(String s, DisplayMode mode, boolean asis)
      Display a string in the Stata Results window and automatically add a line separator at the end.
      static void error​(Object o)
      Display an object in the Stata Results window as an error.
      static void error​(Object o, boolean asis)
      Display an object in the Stata Results window as an error.
      static void error​(String s)
      Display a string in the Stata Results window as an error.
      static void error​(String s, boolean asis)
      Display a string in the Stata Results window as an error.
      static boolean errorDebug​(String s)
      Display a string in the Stata Results window as an error if set debug on is enabled.
      static boolean errorDebug​(String s, boolean asis)
      Display a string in the Stata Results window as an error if set debug on is enabled.
      static boolean errorDebug​(Throwable t)
      Display the stack trace as an error if set debug on is enabled.
      static void errorln​(Object o)
      Display an object in the Stata Results window as an error and automatically add a line separator at the end.
      static void errorln​(String s)
      Display a string in the Stata Results window as an error and automatically add a line separator at the end.
      static int errorMsg​(int rc)
      Display the standard Stata error message associated with return code rc in the Stata Results window.
      static int executeCommand​(String command, boolean echo)
      Execute a Stata command.
      static String formatValue​(double val, String format)
      Format a value using a Stata format.
      static String getAgentString()
      Get the User-Agent that Stata uses for web requests.
      static double getCallerVersion()
      Get the version number of the calling program.
      static String getTempFile()
      Get a valid Stata temporary filename.
      static String getTempName()
      Get a valid Stata temporary name.
      static String getWorkingDir()
      Get the current Stata working directory.
      static boolean isValidName​(String s)
      Check if a String is a valid Stata name.
      static boolean isValidVariableName​(String s)
      Check if a String is a valid Stata variable name.
      static void loadStataProxySettings()
      Apply Stata's proxy settings to Java.
      static int pollnow()
      Request that Stata poll its GUI immediately.
      static int pollstd()
      Request that Stata poll its GUI at the standard interval.
      static String processTildePath​(String path)
      Stata utility to convert a path beginning with a tilde to a user's home directory.
      static File resolvePath​(String path)
      Resolve a path to a File; the path may be relative to Stata's current working directory, begin with a tilde, or be an absolute path.
      static void setRC​(int rc)
      Set the Stata return code when used with Java integration (that is, java[:] blocks).
      static String stackTraceToString​(Exception e)
      Convert the stack trace from an Exception to a String.
      static String stackTraceToString​(Throwable t)
      Convert the stack trace from a Throwable to a String.

    • Method Detail

      • callGC

        @Synchronized
public static void callGC()
        Call the Java garbage collector. Calling this method should generally be avoided.

      • display

        @Synchronized
public static void display​(Object o)
        Display an object in the Stata Results window. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        o - The object to display.

      • display

        @Synchronized
public static void display​(Object o,
                           boolean asis)
        Display an object in the Stata Results window.
        Parameters:
        o - The object to display.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • display

        @Synchronized
public static void display​(Object o,
                           DisplayMode mode,
                           boolean asis)
        Display an object in the Stata Results window.
        Parameters:
        o - The object to display.
        mode - The DisplayMode.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • display

        @Synchronized
public static void display​(String s)
        Display a string in the Stata Results window. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        s - The string to display.

      • display

        @Synchronized
public static void display​(String s,
                           boolean asis)
        Display a string in the Stata Results window.
        Parameters:
        s - The string to display.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • display

        @Synchronized
public static void display​(String s,
                           DisplayMode mode,
                           boolean asis)
        Display a string in the Stata Results window.
        Parameters:
        s - The string to display.
        mode - The DisplayMode.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • displayln

        @Synchronized
public static void displayln()
        Send a line separator to the output.

      • displayln

        @Synchronized
public static void displayln​(Object o)
        Display an object in the Stata Results window and automatically add a line separator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        o - The object to display.

      • displayln

        @Synchronized
public static void displayln​(Object o,
                             boolean asis)
        Display an object in the Stata Results window and automatically add a line separator at the end.
        Parameters:
        o - The object to display.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • displayln

        @Synchronized
public static void displayln​(Object o,
                             DisplayMode mode)
        Display an object in the Stata Results window and automatically add a line separator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        o - The object to display.
        mode - The DisplayMode.

      • displayln

        @Synchronized
public static void displayln​(Object o,
                             DisplayMode mode,
                             boolean asis)
        Display an object in the Stata Results window and automatically add a line separator at the end.
        Parameters:
        o - The object to display.
        mode - The DisplayMode.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • displayln

        @Synchronized
public static void displayln​(String s)
        Display a string in the Stata Results window and automatically add a line separator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        s - The string to display.

      • displayln

        @Synchronized
public static void displayln​(String s,
                             DisplayMode mode)
        Display a string in the Stata Results window and automatically add a line separator at the end.
        Parameters:
        s - The string to display.
        mode - The DisplayMode.

      • displayln

        @Synchronized
public static void displayln​(String s,
                             DisplayMode mode,
                             boolean asis)
        Display a string in the Stata Results window and automatically add a line separator at the end.
        Parameters:
        s - The string to display.
        mode - The DisplayMode.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • error

        @Synchronized
public static void error​(Object o)
        Display an object in the Stata Results window as an error. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        o - The object to display.

      • error

        @Synchronized
public static void error​(Object o,
                         boolean asis)
        Display an object in the Stata Results window as an error.
        Parameters:
        o - The object to display.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • error

        @Synchronized
public static void error​(String s)
        Display a string in the Stata Results window as an error. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        s - The string to display.

      • error

        @Synchronized
public static void error​(String s,
                         boolean asis)
        Display a string in the Stata Results window as an error.
        Parameters:
        s - The string to display.
        asis - When true, the string is printed without using the Stata SMCL interpreter.

      • errorDebug

        @Synchronized
public static boolean errorDebug​(String s)
        Display a string in the Stata Results window as an error if set debug on is enabled. The string will not be run through the Stata SMCL interpreter.
        Parameters:
        s - The string to display.
        Returns:
        True if set debug on is enabled.

      • errorDebug

        @Synchronized
public static boolean errorDebug​(String s,
                                 boolean asis)
        Display a string in the Stata Results window as an error if set debug on is enabled.
        Parameters:
        s - The string to display.
        asis - When true, the string is printed without using the Stata SMCL interpreter.
        Returns:
        True if set debug on is enabled.

      • errorDebug

        @Synchronized
public static boolean errorDebug​(Throwable t)
        Display the stack trace as an error if set debug on is enabled.
        Parameters:
        t - The throwable containing the stack trace to display.
        Returns:
        True if set debug on is enabled.

      • errorln

        @Synchronized
public static void errorln​(Object o)
        Display an object in the Stata Results window as an error and automatically add a line separator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        o - The object to display.

      • errorln

        @Synchronized
public static void errorln​(String s)
        Display a string in the Stata Results window as an error and automatically add a line separator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.
        Parameters:
        s - The string to display.

      • errorMsg

        @Synchronized
public static int errorMsg​(int rc)
        Display the standard Stata error message associated with return code rc in the Stata Results window.
        Parameters:
        rc - The return code for the error.
        Returns:
        The return code for the error.

      • executeCommand

        @SynchronizedOnMain
public static int executeCommand​(String command,
                                 boolean echo)
        Execute a Stata command. This feature is not supported for use with Java integration (that is, java[:] blocks).
        Parameters:
        command - The command to execute.
        echo - Echo the command.
        Returns:
        Return code from Stata; 0 if successful.

      • formatValue

        @ThreadSafe
public static String formatValue​(double val,
                                 String format)
        Format a value using a Stata format.
        Parameters:
        val - The value to format.
        format - A valid Stata format.
        Returns:
        The formatted value in String form. Returns a null String if an error occurs.

      • getAgentString

        public static String getAgentString()
        Get the User-Agent that Stata uses for web requests. This can be useful for setting the request property for a URLConnection.
        For example, 
         URLConnection conn = url.openConnection();
 conn.setRequestProperty("User-Agent", SFIToolkit.getAgentString());
        Returns:
        The agent string.

      • getCallerVersion

        @Synchronized
public static double getCallerVersion()
        Get the version number of the calling program. This function can be used to implement Stata version control.
        Returns:
        The caller's version number.

      • getTempFile

        @Synchronized
public static String getTempFile()
        Get a valid Stata temporary filename.
        Returns:
        The filename, including its path.

      • getTempName

        @Synchronized
public static String getTempName()
        Get a valid Stata temporary name.
        Returns:
        The temporary name.

      • getWorkingDir

        @Synchronized
public static String getWorkingDir()
        Get the current Stata working directory.
        Returns:
        The path of the current working directory.

      • isValidName

        @ThreadSafe
public static boolean isValidName​(String s)
        Check if a String is a valid Stata name.
        Parameters:
        s - Name to test.
        Returns:
        True if the String represents a valid Stata name.

      • isValidVariableName

        @ThreadSafe
public static boolean isValidVariableName​(String s)
        Check if a String is a valid Stata variable name.
        Parameters:
        s - Name to test.
        Returns:
        True if the String represents a valid Stata variable name.

      • loadStataProxySettings

        public static void loadStataProxySettings()
        Apply Stata's proxy settings to Java. Call this prior to making a web request where you want proxy settings to be applied. This method only needs to be called once.

      • pollnow

        @ThreadSafe
public static int pollnow()
        Request that Stata poll its GUI immediately. Use this method inside a time-consuming task so that the Stata interface is responsive to user inputs. Generally, pollstd should be used instead. This method must be called from the main thread. If called from a worker thread, this method does nothing and returns 0.
        Returns:
        A 0 unless the Break key has been pressed.

      • pollstd

        @ThreadSafe
public static int pollstd()
        Request that Stata poll its GUI at the standard interval. Use this method inside a time-consuming task so that the Stata interface is responsive to user inputs. This method must be called from the main thread. If called from a worker thread, this method does nothing and returns 0.
        Returns:
        A 0 unless the Break key has been pressed.

      • processTildePath

        @Synchronized
public static String processTildePath​(String path)
        Stata utility to convert a path beginning with a tilde to a user's home directory. If the path does not begin with a tilde, then the path will not be modified.
        Parameters:
        path - Path to process.
        Returns:
        The processed path.

      • resolvePath

        @Synchronized
public static File resolvePath​(String path)
                        throws InvalidPathException
        Resolve a path to a File; the path may be relative to Stata's current working directory, begin with a tilde, or be an absolute path.
        Parameters:
        path - Path to process.
        Returns:
        A File.
        Throws:
        InvalidPathException - If an error occurs an InvalidPathException is thrown.

      • setRC

        @Synchronized
public static void setRC​(int rc)
        Set the Stata return code when used with Java integration (that is, java[:] blocks). If this method is called within a plugin invoked with javacall, the return code will be overwritten when javacall exits.
        Parameters:
        rc - The return code to set.