org.rosuda.REngine
Class REXPReference

java.lang.Object
  org.rosuda.REngine.REXP
      org.rosuda.REngine.REXPReference

public class REXPReference
extends REXP

this class represents a reference (proxy) to an R object.

The reference semantics works by calling resolve() (which in turn uses REngine.resolveReference(REXP) on itself) whenever any methods are accessed. The implementation is not finalized yat and may change as we approach the JRI interface which is more ameanable to reference-style access. Subclasses are free to implement more efficient implementations.

Field Summary

protected REngine	eng engine which will be used to resolve the reference
protected java.lang.Object	handle an opaque (optional) handle
protected REXP	resolvedValue resolved (cached) object

Fields inherited from class org.rosuda.REngine.REXP

attr, maxDebugItems

Constructor Summary

REXPReference(REngine eng, java.lang.Object handle)
create an external REXP reference using given engine and handle.

Method Summary

REXPList	_attr() this method allows a limited access to object's attributes - REXP.getAttribute(java.lang.String) should be used instead to access specific attributes!.
double[]	asDoubles() returns the contents as an array of doubles (if supported by the represented object)
RFactor	asFactor() returns the contents as a factor (if supported by the represented object)
int[]	asIntegers() returns the contents as an array of integers (if supported by the represented object)
RList	asList() returns the contents as a (named) list (if supported by the represented object)
java.lang.String[]	asStrings() returns the contents as an array of Strings (if supported by the represented object)
protected void	finalize() finalization that notifies the engine when a reference gets collected
REngine	getEngine()
java.lang.Object	getHandle()
void	invalidate() invalidates any cached representation of the reference
boolean	isComplex() check whether the REXP object is a complex vector
boolean	isEnvironment() check whether the REXP object is an environment
boolean	isFactor() check whether the REXP object is a factor
boolean	isInteger() check whether the REXP object is an integer vector
boolean	isLanguage() check whether the REXP object is a language object
boolean	isList() check whether the REXP object is a list (either generic vector or a pairlist - i.e.
boolean	isLogical() check whether the REXP object is a logical vector
boolean	isNull() check whether the REXP object is NULL
boolean	isNumeric() check whether the REXP object is a numeric vector
boolean	isRaw() check whether the REXP object is a raw vector
boolean	isRecursive() check whether the REXP object is a recursive obejct
boolean	isReference() check whether the REXP object is a reference to an R object
boolean	isString() check whether the REXP object is a character vector (string)
boolean	isSymbol() check whether the REXP object is a symbol
boolean	isVector() check whether the REXP object is a vector
int	length() returns the length of a vector object.
REXP	resolve() resolve the external REXP reference into an actual REXP object.
java.lang.String	toString() returns a string description of the object

Methods inherited from class org.rosuda.REngine.REXP

asBytes, asDouble, asDoubleMatrix, asInteger, asNativeJavaObject, asString, createDataFrame, dim, getAttribute, hasAttribute, inherits, isExpression, isNA, isPairList, toDebugString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

eng

protected REngine eng

engine which will be used to resolve the reference

handle

protected java.lang.Object handle

an opaque (optional) handle

resolvedValue

protected REXP resolvedValue

resolved (cached) object

Constructor Detail

REXPReference

public REXPReference(REngine eng,
                     java.lang.Object handle)

create an external REXP reference using given engine and handle. The handle value is just an (optional) identifier not used by the implementation directly.

Method Detail

resolve

public REXP resolve()

resolve the external REXP reference into an actual REXP object. In addition, the value (if not null) will be cached for subsequent calls to resolve until invalidate is called.

invalidate

public void invalidate()

invalidates any cached representation of the reference

finalize

protected void finalize()
                 throws java.lang.Throwable

finalization that notifies the engine when a reference gets collected

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

isString

public boolean isString()

Description copied from class: REXP

check whether the REXP object is a character vector (string)

Overrides:

isString in class REXP

Returns:

true if the receiver is a character vector, false otherwise

isNumeric

public boolean isNumeric()

Description copied from class: REXP

check whether the REXP object is a numeric vector

Overrides:

isNumeric in class REXP

Returns:

true if the receiver is a numeric vector, false otherwise

isInteger

public boolean isInteger()

Description copied from class: REXP

check whether the REXP object is an integer vector

Overrides:

isInteger in class REXP

Returns:

true if the receiver is an integer vector, false otherwise

isNull

public boolean isNull()

Description copied from class: REXP

check whether the REXP object is NULL

Overrides:

isNull in class REXP

Returns:

true if the receiver is NULL, false otherwise

isFactor

public boolean isFactor()

Description copied from class: REXP

check whether the REXP object is a factor

Overrides:

isFactor in class REXP

Returns:

true if the receiver is a factor, false otherwise

isList

public boolean isList()

Description copied from class: REXP

check whether the REXP object is a list (either generic vector or a pairlist - i.e. REXP.asList() will succeed)

Overrides:

isList in class REXP

Returns:

true if the receiver is a generic vector or a pair-list, false otherwise

isLogical

public boolean isLogical()

Description copied from class: REXP

check whether the REXP object is a logical vector

Overrides:

isLogical in class REXP

Returns:

true if the receiver is a logical vector, false otherwise

isEnvironment

public boolean isEnvironment()

Description copied from class: REXP

check whether the REXP object is an environment

Overrides:

isEnvironment in class REXP

Returns:

true if the receiver is an environment, false otherwise

isLanguage

public boolean isLanguage()

Description copied from class: REXP

check whether the REXP object is a language object

Overrides:

isLanguage in class REXP

Returns:

true if the receiver is a language object, false otherwise

isSymbol

public boolean isSymbol()

Description copied from class: REXP

check whether the REXP object is a symbol

Overrides:

isSymbol in class REXP

Returns:

true if the receiver is a symbol, false otherwise

isVector

public boolean isVector()

Description copied from class: REXP

check whether the REXP object is a vector

Overrides:

isVector in class REXP

Returns:

true if the receiver is a vector, false otherwise

isRaw

public boolean isRaw()

Description copied from class: REXP

check whether the REXP object is a raw vector

Overrides:

isRaw in class REXP

Returns:

true if the receiver is a raw vector, false otherwise

isComplex

public boolean isComplex()

Description copied from class: REXP

check whether the REXP object is a complex vector

Overrides:

isComplex in class REXP

Returns:

true if the receiver is a complex vector, false otherwise

isRecursive

public boolean isRecursive()

Description copied from class: REXP

check whether the REXP object is a recursive obejct

Overrides:

isRecursive in class REXP

Returns:

true if the receiver is a recursive object, false otherwise

isReference

public boolean isReference()

Description copied from class: REXP

check whether the REXP object is a reference to an R object

Overrides:

isReference in class REXP

Returns:

true if the receiver is a reference, false otherwise

asStrings

public java.lang.String[] asStrings()
                             throws REXPMismatchException

Description copied from class: REXP

returns the contents as an array of Strings (if supported by the represented object)

Overrides:

asStrings in class REXP

Throws:

REXPMismatchException

asIntegers

public int[] asIntegers()
                 throws REXPMismatchException

Description copied from class: REXP

returns the contents as an array of integers (if supported by the represented object)

Overrides:

asIntegers in class REXP

Throws:

REXPMismatchException

asDoubles

public double[] asDoubles()
                   throws REXPMismatchException

Description copied from class: REXP

returns the contents as an array of doubles (if supported by the represented object)

Overrides:

asDoubles in class REXP

Throws:

REXPMismatchException

asList

public RList asList()
             throws REXPMismatchException

Description copied from class: REXP

returns the contents as a (named) list (if supported by the represented object)

Overrides:

asList in class REXP

Throws:

REXPMismatchException

asFactor

public RFactor asFactor()
                 throws REXPMismatchException

Description copied from class: REXP

returns the contents as a factor (if supported by the represented object)

Overrides:

asFactor in class REXP

Throws:

REXPMismatchException

length

public int length()
           throws REXPMismatchException

Description copied from class: REXP

returns the length of a vector object. Note that we use R semantics here, i.e. a matrix will have a length of m * n since it is represented by a single vector (see REXP.dim() for retrieving matrix and multidimentional-array dimensions).

Overrides:

length in class REXP

Returns:

length (number of elements) in a vector object

Throws:

REXPMismatchException - if this is not a vector object

_attr

public REXPList _attr()

Description copied from class: REXP

this method allows a limited access to object's attributes - REXP.getAttribute(java.lang.String) should be used instead to access specific attributes!. Note that the REXP.attr attribute should never be used directly incase the REXP implements a lazy access (e.g. via a reference)

Overrides:

_attr in class REXP

Returns:

list of attributes or null if the object has no attributes

getHandle

public java.lang.Object getHandle()

getEngine

public REngine getEngine()

toString

public java.lang.String toString()

Description copied from class: REXP

returns a string description of the object

Overrides:

toString in class REXP

Returns:

string describing the object - it can be of an arbitrary form and used only for debugging (do not confuse with REXP.asString() for accessing string REXPs)