\name{converters}
\alias{converters}
\alias{cvtCharacterFromJava}
\alias{cvtCharacterToJava}
\alias{matchCharacterToJava}
\alias{cvtIntegerFromJava}
\alias{cvtIntegerToJava}
\alias{matchIntegerToJava}
\alias{cvtLogicalFromJava}
\alias{cvtLogicalToJava}
\alias{matchLogicalToJava}
\alias{cvtNumericFromJava}
\alias{cvtNumericToJava}
\alias{matchNumericToJava}
\alias{cvtRawFromJava}
\alias{cvtRawToJava}
\alias{matchRawToJava}
\alias{cvtComplexFromJava}
\alias{cvtComplexToJava}
\alias{matchComplexToJava}
\alias{cvtVectorFromJava}
\alias{cvtVectorToJava}
\alias{matchVectorToJava}
\alias{cvtListFromJava}
\alias{cvtListToJava}
\alias{matchListToJava}
\alias{cvtArrayFromJava}
\alias{cvtArrayToJava}
\alias{matchArrayToJava}
\alias{cvtFileReferencesFromJava}
\alias{cvtFileReferencesToJava}
\alias{matchFileReferencesToJava}

\alias{cvtMatrixFromJava}
\alias{cvtMatrixToJava}
\alias{matchMatrixToJava}
\alias{cvtFactorFromJava}
\alias{cvtFactorToJava}
\alias{matchFactorToJava}
\alias{cvtDataFrameFromJava}
\alias{cvtDataFrameToJava}
\alias{matchDataFrameToJava}
\alias{cvtEnvFromJava}
\alias{cvtEnvToJava}
\alias{matchEnvToJava}
\alias{cvtUnknownFromJava}
\alias{cvtUnknownToJava}
\alias{matchUnknownToJava}
\alias{cvtCharacterToJava2}
\alias{matchCharacterToJava2}
\alias{cvtIntegerToJava2}
\alias{matchIntegerToJava2}
\alias{cvtLogicalToJava2}
\alias{matchLogicalToJava2}
\alias{cvtNumericToJava2}
\alias{matchNumericToJava2}
\alias{cvtRawToJava2}
\alias{matchRawToJava2}
\alias{cvtComplexFromJava2}
\alias{cvtComplexToJava2}
\alias{matchComplexToJava2}
\alias{cvtListToJava2}
\alias{matchListToJava2}
\alias{cvtFactorFromJava2}
\alias{cvtFactorToJava2}
\alias{matchFactorToJava2}
\alias{cvtDataFrameFromJava2}
\alias{cvtDataFrameToJava2}
\alias{matchDataFrameToJava2}
\alias{cvtCharArrayFromJava2}
\alias{cvtCharArrayToJava2}
\alias{matchCharArrayToJava2}
\alias{cvtIntegerArrayFromJava2}
\alias{cvtIntegerArrayToJava2}
\alias{matchIntegerArrayToJava2}
\alias{cvtNumericArrayFromJava2}
\alias{cvtNumericArrayToJava2}
\alias{matchNumericArrayToJava2}
\alias{cvtLogicalArrayFromJava2}
\alias{cvtLogicalArrayToJava2}
\alias{matchLogicalArrayToJava2}
\alias{cvtRawArrayFromJava2}
\alias{cvtRawArrayToJava2}
\alias{matchRawArrayToJava2}
\alias{cvtComplexArrayFromJava2}
\alias{cvtComplexArrayToJava2}
\alias{matchComplexArrayToJava2}
\alias{cvtCharMatrixFromJava2}
\alias{cvtCharMatrixToJava2}
\alias{matchCharMatrixToJava2}
\alias{cvtIntegerMatrixFromJava2}
\alias{cvtIntegerMatrixToJava2}
\alias{matchIntegerMatrixToJava2}
\alias{cvtNumericMatrixFromJava2}
\alias{cvtNumericMatrixToJava2}
\alias{matchNumericMatrixToJava2}
\alias{cvtLogicalMatrixFromJava2}
\alias{cvtLogicalMatrixToJava2}
\alias{matchLogicalMatrixToJava2}
\alias{cvtRawMatrixFromJava2}
\alias{cvtRawMatrixToJava2}
\alias{matchRawMatrixToJava2}
\alias{cvtComplexMatrixFromJava2}
\alias{cvtComplexMatrixToJava2}
\alias{matchComplexMatrixToJava2}
\alias{cvtEnvFromJava2}
\alias{cvtEnvToJava2}
\alias{matchEnvToJava2}
\alias{cvtFileReferencesFromJava2}
\alias{cvtFileReferencesToJava2}
\alias{matchFileReferencesToJava2}

\title{
  Convert between R objects and their Java representation. 
}

\description{
  These functions are not intended for the end user. They are used to
  match objects being translated between R and Java to functions that
  perform the conversion. They are useful for understanding the overall
  conversion process, and as examples for writing custom conversions.
}

\usage{
# 'robject' converters
cvtCharacterFromJava(x, thisClassName)
cvtCharacterToJava(x, ...)
matchCharacterToJava(x, ...)

cvtIntegerFromJava(x, thisClassName)
cvtIntegerToJava(x, ...)
matchIntegerToJava(x, ...)

cvtLogicalFromJava(x, thisClassName)
cvtLogicalToJava(x, ...)
matchLogicalToJava(x, ...)

cvtNumericFromJava(x, thisClassName)
cvtNumericToJava(x, ...)
matchNumericToJava(x, ...)

cvtRawFromJava(x, thisClassName)
cvtRawToJava(x, ...)
matchRawToJava(x, ...)

cvtComplexFromJava(x, thisClassName)
cvtComplexToJava(x, ...)
matchComplexToJava(x, ...)

cvtVectorFromJava(x, thisClassName)
cvtVectorToJava(x, ...)
matchVectorToJava(x, ...)

cvtListFromJava(x, thisClassName)
cvtListToJava(x, ...)
matchListToJava(x, ...)

cvtArrayFromJava(x, thisClassName)
cvtArrayToJava(x, ...)
matchArrayToJava(x, ...)

cvtMatrixFromJava(x, thisClassName)
cvtMatrixToJava(x, ...)
matchMatrixToJava(x, ...)

cvtFactorFromJava(x, thisClassName)
cvtFactorToJava(x, ...)
matchFactorToJava(x, ...)

cvtDataFrameFromJava(x, thisClassName)
cvtDataFrameToJava(x, ...)
matchDataFrameToJava(x, ...)

cvtEnvFromJava(x, thisClassName)
cvtEnvToJava(x, ...)
matchEnvToJava(x, ...)

cvtUnknownFromJava(x, thisClassName)
cvtUnknownToJava(x, ...)
matchUnknownToJava(x, ...)

cvtFileReferencesFromJava(x, thisClassName)
cvtFileReferencesToJava(x, ...)
matchFileReferencesToJava(x, ...)

## 'javalib' converters
cvtCharacterToJava2(x, ...)
matchCharacterToJava2(x, ...)

cvtIntegerToJava2(x, ...)
matchIntegerToJava2(x, ...)

cvtLogicalToJava2(x, ...)
matchLogicalToJava2(x, ...)

cvtNumericToJava2(x, ...)
matchNumericToJava2(x, ...)

cvtRawToJava2(x, ...)
matchRawToJava2(x, ...)

cvtComplexFromJava2(x, thisClassName)
cvtComplexToJava2(x, ...)
matchComplexToJava2(x, ...)

cvtListToJava2(x, ...)
matchListToJava2(x, ...)

cvtFactorFromJava2(x, thisClassName)
cvtFactorToJava2(x, ...)
matchFactorToJava2(x, ...)

cvtDataFrameFromJava2(x, thisClassName)
cvtDataFrameToJava2(x, ...)
matchDataFrameToJava2(x, ...)

cvtCharArrayFromJava2(x, thisClassName)
cvtCharArrayToJava2(x, ...)
matchCharArrayToJava2(x, ...)

cvtIntegerArrayFromJava2(x, thisClassName)
cvtIntegerArrayToJava2(x, ...)
matchIntegerArrayToJava2(x, ...)

cvtNumericArrayFromJava2(x, thisClassName)
cvtNumericArrayToJava2(x, ...)
matchNumericArrayToJava2(x, ...)

cvtLogicalArrayFromJava2(x, thisClassName)
cvtLogicalArrayToJava2(x, ...)
matchLogicalArrayToJava2(x, ...)

cvtRawArrayFromJava2(x, thisClassName)
cvtRawArrayToJava2(x, ...)
matchRawArrayToJava2(x, ...)

cvtComplexArrayFromJava2(x, thisClassName)
cvtComplexArrayToJava2(x, ...)
matchComplexArrayToJava2(x, ...)

cvtCharMatrixFromJava2(x, thisClassName)
cvtCharMatrixToJava2(x, ...)
matchCharMatrixToJava2(x, ...)

cvtIntegerMatrixFromJava2(x, thisClassName)
cvtIntegerMatrixToJava2(x, ...)
matchIntegerMatrixToJava2(x, ...)

cvtNumericMatrixFromJava2(x, thisClassName)
cvtNumericMatrixToJava2(x, ...)
matchNumericMatrixToJava2(x, ...)

cvtLogicalMatrixFromJava2(x, thisClassName)
cvtLogicalMatrixToJava2(x, ...)
matchLogicalMatrixToJava2(x, ...)

cvtRawMatrixFromJava2(x, thisClassName)
cvtRawMatrixToJava2(x, ...)
matchRawMatrixToJava2(x, ...)

cvtComplexMatrixFromJava2(x, thisClassName)
cvtComplexMatrixToJava2(x, ...)
matchComplexMatrixToJava2(x, ...)

cvtEnvFromJava2(x, thisClassName)
cvtEnvToJava2(x, ...)
matchEnvToJava2(x, ...)

cvtFileReferencesFromJava2(x, thisClassName)
cvtFileReferencesToJava2(x, ...)
matchFileReferencesToJava2(x, ...)
}

\arguments{
 \item{x}{Either a reference to the Java object to be converted (e.g. \code{cvtArrayFromJava}), or a \R{} object.} 
 \item{...}{Additional arguments passed to SJava}
 \item{thisClassName}{Character representation of the class of the Java object that \code{x} refers to.} 
}

\details{
  The \code{cvt*} functions take an instance of an object of one
  language (R or Java) and convert it to an instance of the other
  language.

  The \code{match*} functions take an instance of an object, and return
  a logical indicating whether the match criterion is satisified.

  The convention used in RWebServices is to name the functions as
  \code{<RObject>ToJava} or \code{<RObject>FromJava}. 

  \code{RWebServices} installs one of two types of converters. The
  the function \code{\link{regAddonCvt}} installs converters for the
  \sQuote{robject} model, where R objects are represented in a hierarchy
  of Java objects that attempt to capture important attributes of the R
  instances. The mapping is as follows:

  \tabular{ll}{
	R \tab Java \cr
	raw \tab RRaw \cr
	logical \tab RLogical \cr
	character \tab RChar \cr
	integer \tab RInteger \cr
	numeric \tab RNumeric \cr
	complex \tab RComplex \cr

	list \tab RList \cr
	factor \tab RFactor \cr
	data.frame \tab RDataFrame \cr
	environment \tab REnvironment \cr

	array \tab RArray \cr
	matrix \tab RMatrix \cr
	\sQuote{other} \tab RUnknown
  }

  The \sQuote{other} converter is invoked when no other converter
  matches. \code{cvtUnknownToJava} creates an instance of the Java class
  \code{rservices.RUnknown} to hold the \code{class}, \code{length}, and
  string representation (i.e., the result of \code{print}) of the contents
  of the \R{} object. \code{cvtUnknownFromJava} converts
  \code{rservices.RUnknown} instance to a \R{} S4 instance if the original
  R object is a S4 instance, otherwise the function returns a list with the
  same \code{class} and \code{length} as the original R object. This is
  likely to be very unsatisfactory.

  The function \code{\link{regAddonCvt2}} installs converters for the
  \sQuote{javalib} model, where R objects are represented by Java
  primitive types where possible; \code{NA} values are not
  permitted. The mapping is as follows:

  \tabular{ll}{
	R \tab Java \cr
	raw \tab byte[] \cr
	logical \tab boolean[] \cr
	character \tab String[] \cr
	integer \tab int[] \cr
	numeric \tab double[] \cr
	complex \tab RJComplex \cr

	list \tab Object[] \cr
	factor \tab RJFactor \cr
	data.frame \tab RJDataFrame \cr
	environment \tab java.util.HashMap \cr

	\sQuote{*}Array, \tab RJ\sQuote{*}Array \cr
	\sQuote{*}Matrix, \tab RJ\sQuote{*}Matrix \cr

    FileReferences \tab RJFileReferences \cr
  }

  The \sQuote{*}Array and \sQuote{*}Matrix and array entries represent
  instances of the \code{\link{ArrayAndMatrix-class}}, which provide
  strong type information about the \code{typeof} elements (raw,
  logical, character, integer, numeric, complex) in arrays and
  matricies.
}
\value{
  The \code{cvt*ToJava} functions return references to Java objects. The
  \code{cvt*FromJava} functions return instances of R
  objects. \code{match*} return \code{TRUE} when the match criterion is
  satisfied, \code{FALSE} otherwise.
}
\references{
 \url{http://www.omegahat.org/RSJava/index.html}
}
\author{Nianhua Li}
\seealso{
  \code{\link[SJava]{setJavaFunctionConverter}},
  \code{\link{regAddonCvt}},
  \code{\link{regAddonCvt2}}
}
\keyword{interface}