Package com.stata.sfi

Class SFIToolkit

java.lang.Object
com.stata.sfi.SFIToolkit
public final class SFIToolkit extends Object
This class provides a set of core tools for interacting with Stata.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    RC_BREAK
     
    static final int
    RC_GENERAL_ERROR
     
    static final int
    RC_GENERAL_EXCEPTION
     
    static final int
    RC_SYNTAX_ERROR
     

  • Method Summary

    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.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Method Details

    • 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)
      Display an object in the Stata Results window.
      Parameters:
      o - The object to display.
      mode - The DisplayMode.

    • 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)
      Display a string in the Stata Results window.
      Parameters:
      s - The string to display.
      mode - The DisplayMode.

    • 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.

    • stackTraceToString

      @ThreadSafe public static String stackTraceToString(Exception e)
      Convert the stack trace from an Exception to a String.
      Parameters:
      e - Exception.
      Returns:
      The String representation of the stack trace.

    • stackTraceToString

      @ThreadSafe public static String stackTraceToString(Throwable t)
      Convert the stack trace from a Throwable to a String.
      Parameters:
      t - Throwable.
      Returns:
      The String representation of the stack trace.