\HeaderA{updateObject}{Update an object to its current class definition}{updateObject}
\aliasA{getObjectSlots}{updateObject}{getObjectSlots}
\aliasA{updateObject,ANY-method}{updateObject}{updateObject,ANY.Rdash.method}
\aliasA{updateObject,environment-method}{updateObject}{updateObject,environment.Rdash.method}
\aliasA{updateObject,list-method}{updateObject}{updateObject,list.Rdash.method}
\aliasA{updateObjectFromSlots}{updateObject}{updateObjectFromSlots}
\aliasA{updateObjectTo}{updateObject}{updateObjectTo}
\aliasA{updateObjectTo,ANY,ANY-method}{updateObject}{updateObjectTo,ANY,ANY.Rdash.method}
\keyword{manip}{updateObject}
\begin{Description}\relax
These generic functions return an instance of \code{object} updated to
its current class definition (or to the class definition of
\code{template}, in the case of \code{updateObjectTo}).

Updating objects is primarily useful when an object has been
serialized (e.g., stored to disk) for some time (e.g., months), and the
class definition has in the mean time changed. Because of the changed
class definition, the serialized instance is no longer valid.

\code{updateObject} requires that the class of the returned object be
the same as the class of the argument \code{object}, and that the
object is valid (see \code{\LinkA{validObject}{validObject}}). By default,
\code{updateObject} has the following behaviors:
\describe{
\item[\code{updateObject(ANY, ..., verbose=FALSE)}] By default,
\code{updateObject} uses heuristic methods to determine whether
the object should be the `new' S4 type (introduced in R 2.4.0),
but is not. If the heuristics indicate an update is required, 
the \code{\LinkA{updateObjectFromSlots}{updateObjectFromSlots}} function tries to update the
object. The default method returns the original S4 object or the successfully
updated object, or issues an error if an update is required but
not possible. The optional
named argument \code{verbose} causes a message to be printed describing
the action. Arguments \code{...} are passed to \code{link\{updateObjectFromSlots\}}.
\item[\code{updateObject(list, ..., verbose=FALSE)}] Visit each element in \code{list},
applying \code{updateObject(list[[elt]], ..., verbose=verbose)}.
\item[\code{updateObject(environment, ..., verbose=FALSE)}] Visit
each element in \code{environment}, applying
\code{updateObject(environment[[elt]], ..., verbose=verbose)}
}

\code{updateObjectTo} requires that the class of the returned object
be the same as the class of the \code{template} argument, and that the
object is valid. Usually, updating proceeds by modifying slots in
\code{template} with information from \code{object}, and returning
\code{template}. Use \code{\LinkA{as}{as}} to coerce an object from one
type to another; \code{updateObjectTo} might be useful to update a
virtual superclass. By default, \code{updateObjectTo} has the following
behavior:
\describe{
\item[\code{updateObjectTo(ANY-object,ANY-template)}] Attempt \code{as(ANY-object,class(ANY-template))}.
}

Sample methods are illustrated below.

\code{updateObjectFromSlots(object, objclass = class(object), ..., verbose=FALSE)} is a
utility function that identifies the intersection of slots defined in
the \code{object} instance and \code{objclass} definition. The
corresponding elements in \code{object} are then updated (with
\code{updateObject(elt, ..., verbose=verbose)}) and used as arguments to
a call to \code{new(class, ...)}, with \code{...} replaced by slots
from the original object. If this fails, \code{updateObjectFromSlots}
then tries \code{new(class)} and assigns slots of \code{object} to
the newly created instance.

\code{getObjectSlots(object)} extracts the slot names and contents from
\code{object}. This is useful when \code{object} was created by a class
definition that is no longer current, and hence the contents of
\code{object} cannot be determined by accessing known slots.
\end{Description}
\begin{Usage}
\begin{verbatim}
updateObject(object, ..., verbose=FALSE)
updateObjectTo(object, template, ..., verbose=FALSE)
updateObjectFromSlots(object, objclass=class(object), ..., verbose=FALSE)
getObjectSlots(object)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] Object to be updated, or for slot information to be
extracted from.
\item[\code{template}] Instance representing a template for updating object.
\item[\code{objclass}] Optional character string naming the class of the object to be created.
\item[\code{verbose}] A logical, indicating whether information about the
update should be reported. Use \code{message} to report this.
\item[\code{...}] Additional arguments, for use in specific update methods
\end{ldescription}
\end{Arguments}
\begin{Value}
\code{updateObject} returns a valid instance of \code{object}.
\code{updateObjectTo} returns a valid instance of \code{template}.
\code{updateObjectFromSlots} returns an instance of class \code{objclass}.
\code{getObjectSlots} returns a list of named elements, with each
element corresponding to a slot in \code{object}.
\end{Value}
\begin{Author}\relax
Biocore team
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{Versions-class}{Versions.Rdash.class}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## update object, same class
data(sample.ExpressionSet)
obj <- updateObject(sample.ExpressionSet)

## Not run: 
## generally, use 'as' to coerce objects between classes
data(sample.exprSet)
obj <- as(sample.exprSet, "ExpressionSet")
## End(Not run)

setClass("UpdtA", representation(x="numeric"), contains="data.frame")
setMethod("updateObject", signature(object="UpdtA"),
          function(object, ..., verbose=FALSE) {
              if (verbose) message("updateObject object = 'A'")
              object <- callNextMethod()
              object@x <- -object@x
              object
})

a <- new("UpdtA", x=1:10)
## See steps involved
updateObject(a)

removeClass("UpdtA")
removeMethod("updateObject", "UpdtA")
\end{ExampleCode}
\end{Examples}

