\name{updateObject}

\alias{updateObject}
\alias{updateObject,ANY-method}
\alias{updateObject,list-method}
\alias{updateObject,environment-method}
\alias{updateObject,formula-method}
\alias{updateObject,envRefClass-method}

\alias{updateObjectFromSlots}
\alias{getObjectSlots}

\title{Update an object to its current class definition}

\description{
  \code{updateObject} is a generic function that returns an instance
  of \code{object} updated to its current class definition.
}

\usage{
updateObject(object, ..., verbose=FALSE)

## Related utilities:
updateObjectFromSlots(object, objclass=class(object)[[1L]], ...,
                      verbose=FALSE)
getObjectSlots(object)
}

\arguments{
  \item{object}{
    Object to be updated for \code{updateObject} and
    \code{updateObjectFromSlots}.

    Object for slot information to be extracted from for
    \code{getObjectSlots}.
  }
  \item{...}{
    Additional arguments, for use in specific \code{updateObject}
    methods.
  }
  \item{verbose}{
    \code{TRUE} or \code{FALSE}, indicating whether information about
    the update should be reported. Use \code{\link[base]{message}} to
    report this information.
  }
  \item{objclass}{
    Optional character string naming the class of the object
    to be created.
  }
}

\details{
  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{\link[methods]{validObject}}). By default,
  \code{updateObject} has the following behaviors:
  \describe{
    \item{\code{updateObject(ANY, \dots, 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{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{\dots} are passed to \code{updateObjectFromSlots}.
    }
    \item{\code{updateObject(list, \dots, verbose=FALSE)}}{
      Visit each element in \code{list}, applying
      \code{updateObject(list[[elt]], \dots, verbose=verbose)}.
    }
    \item{\code{updateObject(environment, \dots, verbose=FALSE)}}{
      Visit each element in \code{environment}, applying
      \code{updateObject(environment[[elt]], \dots, verbose=verbose)}
    }
    \item{\code{updateObject(formula, \dots, verbose=FALSE)}}{
      Do nothing; the environment of the formula may be too general
      (e.g., \code{R_GlobalEnv}) to attempt an update.
    }
    \item{\code{updateObject(envRefClass, \dots, verbose=FALSE)}}{
      Attempt to update objects from fields using a strategy like
      \code{updateObjectFromSlots} Method 1.
    }
  }

  \code{updateObjectFromSlots(object, objclass=class(object), \dots,
  verbose=FALSE)} is a utility function that identifies the intersection
  of slots defined in the \code{object} instance and \code{objclass}
  definition. Under Method 1, the corresponding elements in
  \code{object} are then updated (with \code{updateObject(elt, \dots,
  verbose=verbose)}) and used as arguments to a call to \code{new(class,
  \dots)}, with \code{\dots} replaced by slots from the original
  object. If this fails, then Method 2 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.
}

\value{
  \code{updateObject} returns a valid instance of \code{object}.

  \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}.
}

\seealso{
  \itemize{
    \item \code{\link[Biobase]{updateObjectTo}} in the \pkg{Biobase} package
          for updating an object to the class definition of a template (might
          be useful for updating a virtual superclass).

    \item \code{\link[methods]{validObject}} for testing the validity of an
          object.

    \item \code{\link[methods]{showMethods}} for displaying a summary of the
          methods defined for a given generic function.

    \item \code{\link[methods]{selectMethod}} for getting the definition of
          a specific method.

    \item \link{BiocGenerics} for a summary of all the generics defined
          in the \pkg{BiocGenerics} package.
  }
}

\examples{
updateObject
showMethods("updateObject")
selectMethod("updateObject", "ANY")  # the default method

library(Biobase)
## update object, same class
data(sample.ExpressionSet)
obj <- updateObject(sample.ExpressionSet)

setClass("UpdtA", representation(x="numeric"), contains="data.frame")
setMethod("updateObject", "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)

removeMethod("updateObject", "UpdtA")
removeClass("UpdtA")
}

\keyword{methods}
