\name{createMap}
\alias{createMap}
\alias{createMap,standardGeneric,missing-method}
\alias{createMap,character,missing-method}
\alias{createMap,missing,character-method}

\title{Create Java function signatures from R functions}
\description{
  \code{createMap} extracts type information from R function
  definitions, and uses this to create Java-style function calls with
  appropriately typed arguments. Types are then converted to Java
  objects.

  A side effect is to create or modify a directory structure in the
  current working directory containing Java class information.

  There are three methods defined:
  \describe{
	\item{\code{createMap(standardGeneric, missing, ...)}}{Intended to
	  dispatch on S4 generics, creating maps for all currently visible
	  methods.}
	\item{\code{createMap(character, missing,  ...)}}{Intended to
	  dispatch on a character vector of function names, creating maps
	  for each function.}
	\item{\code{createMap(missing, pkgs=character, ...)}}{Inteded to map
	  all functions in \code{pkgs} with \code{typeInfo}
	  applied. \code{pkgs} can be a character vecorr of package names,
	  or in conjunction with the argument \code{splitPkgsToVector=TRUE}
	  a comma-delimited list of packages. The latter behavior is meant
	  to faciliate use with the \code{ant} command line, as
	  \code{ant -Dpkg=caDNAcopy,caPROcess gen-map-from-package}.}
	}
}
\usage{
createMap(funcs, pkgs, generateTests = TRUE,
          outputDirectory = stop("specify outputDirectory"),
          typeMode = "javalib", deployMode = "jms",
          verbose = FALSE, ...)
\S4method{createMap}{missing,character}(funcs, pkgs, generateTests = TRUE,
          outputDirectory = stop("specify outputDirectory"),
          typeMode = "javalib", deployMode = "jms",
          verbose = FALSE, splitPkgsToVector=TRUE, ...,
          extraClasses=character())
}

\arguments{
  \item{funcs}{Function or list of functions with typeInfo already
    applied, or S4 generic method.}
  \item{pkgs}{Character string or vector of package names. Package
    namespaces are parsed for functions with TypeInfo, and R-Java maps are
    created for these.}
  \item{generateTests}{Logical. Should test code be generated?}
  \item{outputDirectory}{Directory where Java hierarchy will be
    created.}
  \item{typeMode}{Character, either "robject" or "javalib". How Java
    objects should be generated; see \code{\link{generateDataMap}} and
    \code{\link{converters}}. \code{typemode} may be over-written by
    values in \code{system.file("rservices", "properties.R",
    package=pkg)}.}
  \item{deployMode}{Character, either "demo" or "jms". How the service
    will be deployed. "demo" is no longer supported.}
  \item{verbose}{Print information during mapping generationg; useful
    for debugging.}
  \item{...}{Additional arguments, e.g., \code{S4DefaultTypedSig}
    used for providing type specifications for S4 functions when
    \code{funcs} is of class \code{standardGeneric}, or
	\code{splitPkgsToVector=TRUE} to treat \code{pkgs} as a
	comma-delimited list of packages.}
  \item{splitPkgsToVector}{Parse \code{character(1)} pkgs as
	\code{split(pkgs, ",")}, primarily for ant-based integration.}
  \item{extraClasses}{A character vector of extra classes to map, in
	addition to those specified in the TypeInfo
	signature. \code{extraClasses} for this method are augmented by any
	classes defined in the file \code{system.file("rservices",
	"properties.R", package=pkg)}.}

}
\details{
  \code{createMap} operates either on functions with
  \code{\link[TypeInfo]{typeInfo}} applied, or on S4 generic
  methods.

  Some coercion occurs with \code{typeInfo} functions.  All signatures
  have an explict return type.
  \code{\link[TypeInfo:IndependentTypeSpecification-class]{IndependentTypeSpecification}}
  classes are 'expanded' to a complete set of typed signatures.

  Function signatures for S4 methods are created from information used
  in generic method construction, supplemented by an optional default
  type signature supplied as a named argument \code{S4DefaultTypedSig}. Each method defined for a
  generic results in a Java signature. Arguments used for method
  dispatch are typed according to the dispatch rules for the
  function. Return types are determined by the \code{valueClass} of the
  generic (the \code{valueClass} of methods seem not to defined,
  despite what the documentation indicates). Default values for other
  arguments, and for return values if \code{valueClass} is not used, can
  be created with a
  \code{\link[TypeInfo:TypedSignature-class]{TypedSignature}} passed as
  a named argument \code{S4DefaultTypedSig}. Values implied by S4 method
  definitions override the defaults.

  See \code{\link{typeInfo2Java}} for additional information on how
  conversion occurs.
}
\value{
  Primarily inovkes for the side-effect of creating a java class
  hierarchy reflecting the data and methods present in the call to
  \code{createMap}. Returns a list of Java signatures function definitions..
}
\seealso{\code{\link{createMap,missing,character-method}}}
\author{Martin Morgan <mtmorgan@fhcrc.org>}
\examples{
library(RWebServices)

## S4
\dontrun{
setClass("A", representation(x="character"))
setGeneric("foo", function(obj) standardGeneric("foo"))
setMethod("foo", "numeric", function(obj) new("A", x=as.character(obj)))
setMethod("foo", "character", function(obj) new("A", x=obj))

createMap(foo, outputDirectory=tempdir(), S4DefaultTypedSig=TypedSignature(returnType="A"))

% checkType <- TypeInfo:::checkType
% RJavaSignature(checkType, S4DefaultTypedSig = TypedSignature(returnType = "logical" ))

% createMap(typeInfo2Java, S4DefaultTypedSig=TypedSignature(returnType="RJavaSignature"))
}
}
\keyword{programming}
\keyword{documentation}