1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
\name{jcheck}
\alias{.jcheck}
\alias{.jthrow}
\alias{.jclear}
\alias{.jgetEx}
\title{
Java exception handling
}
\description{
\code{.jcheck} checks the Java VM for any pending exceptions and
clears them.
\code{.jthrow} throws a Java exception.
\code{.jgetEx} polls for any pending exceptions and returns the exception object.
\code{.jclear} clears a pending exception.
}
\usage{
.jcheck(silent = FALSE)
.jthrow(exception, message = NULL)
.jgetEx(clear = FALSE)
.jclear()
}
\arguments{
\item{silent}{If set to \code{FALSE} then Java is instructed to print
the exception on \code{stderr}. Note that Windows Rgui doesn't show
\code{stderr} so it will not appear there (as of rJava 0.5-1 some
errors that the JVM prints using the vfprintf callback are passed
to R. However, some parts are printed using \code{System.err} in
which case the usual redirection using the \code{System} class
can be used by the user).}
\item{exception}{is either a class name of an exception to create or a
throwable object reference that is to be thrown.}
\item{message}{if \code{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 \code{exception} is a reference.}
\item{clear}{if set to \code{TRUE} then the returned exception is also
cleared, otherwise the throwable is returned without clearing the
cause.}
}
\value{
\code{.jcheck} returns \code{TRUE} if an exception occurred or
\code{FALSE} otherwise.
\code{.jgetEx} returns \code{NULL} if there are no pending exceptions
or an object of the class "java.lang.Throwable" representing the
current exception.
}
\details{
Please note that some functions (such as \code{\link{.jnew}} or
\code{\link{.jcall}}) call \code{.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 elaborate system
using constructs similar to \code{try} ... \code{catch} is planned for
next major version of \code{rJava}.
\emph{Warning:} When requesting exceptions to not be cleared
automatically, please note that the \code{show} method (which is
called by \code{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 \code{.jgetEx} can be stored, but should not be printed
(or otherwise used in Java calls) until after the exception is
cleared. In general, all Java calls will fail (possibly silently)
until the exception is cleared.
}
\seealso{
\code{\link{.jcall}}, \code{\link{.jnew}}
}
\examples{
\donttest{
# 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)
}
}
\keyword{interface}
|
