org.rosuda.REngine
Class REXPReference

java.lang.Object
  extended by org.rosuda.REngine.REXP
      extended by 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, createDoubleMatrix, 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)