\name{retrieve-methods}
\docType{methods}
\alias{retrieve}
\alias{retrieve-methods}
\alias{retrieve,FileReferences,character-method}
\alias{retrieve,FileReferences,FileReferences-method}
\alias{retrieve,FileReferences,missing-method}
\title{Retrieve file references from remote locations}
\description{

  This method retrieve files referenced by its first argument to
  locations determined by its second argument. The return value is a
  \code{\linkS4class{FileReferences}} object summarizing the
  destination.

}
\usage{
retrieve(from, to, ...)
}

\arguments{

  \item{from}{The source from which objects will be retrieved; typically
	(or exclusively, depending on method) `remote' locations accessible
	via, e.g., http.}

  \item{to}{The destination to which files will be copied; typically on
	the local file system.}

  \item{...}{Additional arguments, passed to the function performing the
	download.}

}

\section{Methods}{
\describe{

  \item{from = "FileReferences", to = "character"}{\code{from} contains
	remote urls; files must be retrievable using \code{getBinaryURL}
	from the \code{RCurl} package. \code{...}  arguments are passed to
	\code{getBinaryURL}. \code{to} is a directory name to which files
	will be copied; the directory is created if it does not exist. File
	names will be unique.}

  \item{from = "FileReferences", to = "FileReferences"}{\code{from} is
	as in \code{retrieve,FileReferences,character-method}. \code{to}
	specifies destination urls; \code{urls(to)} must have the same
	number of elements as \code{urls{from}}, must not already exist on
	the local file system, and must not require creation of new
	directories. \code{localNames} and \code{types} of \code{to} are
	replaced by corresponding elements from \code{from}.}

  \item{from = "FileReferences", to = "missing"}{\code{from} is as in
	the \code{retrieve,FileReferences,character-method}. The destination
	is created using \code{tempfile()}, and forwarding this as the
	second argument to
	\code{retrieve,FileReferences,character-method}. The effect is to
	retrieve files to R's temporary directory; these files will be
	removed when the R session ends.}

}}
\examples{
try({ # fails when no internet available
    from <- FileReferences(c("http://bioconductor.org/biocLite.R",
                             "http://bioconductor.org/index.html"))
    ## to R's temporary directory
    to <- retrieve(from)
    urls(to)
    localNames(to)

    ## tell R where to copy files to
    toDir <- tempfile()
    dir.create(toDir, recursive=TRUE)
    toUrls <- file.path(toDir, localNames(from))
    retrieve(from, FileReferences(toUrls))
    list.files(toDir)
})
}

\keyword{methods}