jcheck                 package:rJava                 R Documentation

_J_a_v_a _e_x_c_e_p_t_i_o_n _h_a_n_d_l_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     '.jcheck' checks the Java VM for any pending exceptions and clears
     them.

     '.jthrow' throws a Jva exception.

     '.jgetEx' polls for any pending expections and returns the
     exception object.

     '.jclear' clears a pending exception.

_U_s_a_g_e:

     .jcheck(silent = FALSE)

     .jthrow(exception, message = NULL)
     .jgetEx(clear = FALSE)
     .jclear()

_A_r_g_u_m_e_n_t_s:

  silent: If set to 'FALSE' then Java is instructed to print the
          exception on 'stderr'. Note that Windows Rgui doesn't show
          'stderr' so it will not appear there (the printing is done
          internally in the JVM, so there is no simple way to use R's
          I/O).

exception: is either a class name of an exception to create or a
          throwable object reference that is to be thrown.

 message: if 'exception' is a class name then this parameter specifies
          the string to be used as the message of the exception. This
          parameter is ignored if 'exception' is a reference.

   clear: if set to 'TRUE' then the returned exception is also cleared,
          otherwise the throwable is returned without clearing the
          cause.

_D_e_t_a_i_l_s:

     Please note that some functions (such as '.jnew' or '.jcall') call
     '.jcheck' implicitly unless instructed to not do so. If you want
     to handle Java exceptions, you should make sure that those
     function don't clear the exception you may want to catch.

     The exception handling is still as a very low-level and
     experimental, because it requires polling of exceptions. A more
     elaboate system using constructs similar to 'try' ... 'catch' is
     planned for next major version of 'rJava'.

     _Warning:_ When requesting exceptions to not be cleared
     automatically, please note that the 'show' method (which is called
     by 'print') has a side-effect of making a Java call to get the
     string representation of a Java object. This implies that it will
     be impeded by any pending exceptions. Therefore exceptions
     obtained through '.jgetEx' can be stored, but the should not be
     printed (or otherwise used in Java calls) until after the
     exception is cleared. In general, all Java calls will fail until
     the exception is cleared.

_V_a_l_u_e:

     '.jcheck' returns 'TRUE' if an exception occurred or 'FALSE'
     otherwise.

     '.jgetEx' returns 'NULL' if there are no pending exceptions or an
     object of the class "java.lang.Throwable" representing the current
     exception.

_S_e_e _A_l_s_o:

     '.jcall', '.jnew'

_E_x_a_m_p_l_e_s:

     ## Not run: 
     # we try to create a bogus object and
     # instruct .jnew to not clear the exception
     # this will raise an exception
     v <- .jnew("foo/bar", check=FALSE)

     # you can poll for the exception, but don't try to print it
     # (see details above)
     if (!is.null(e<-.jgetEx())) print("Java exception was raised")

     # expect TRUE result here because the exception was still not cleared
     print(.jcheck(silent=TRUE))
     # next invocation will be FALSE because the exception is now cleared
     print(.jcheck(silent=TRUE))

     # now you can print the actual expection (even after it was cleared)
     print(e)
     ## End(Not run)

