• Home
• com.github.lucarosellini.rJava
• REngine
• 0.9-7
• source code

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

carosellini.rJava.REngine.0.9-7.source-code.REngine Maven / Gradle / Ivy

package org.rosuda.REngine;

import java.lang.reflect.Method;

/** REngine is an abstract base class for all implementations of R engines. Subclasses can implement interfaces to R in many different ways.
 Clients should always use methods this class instead of its direct subclasses in order to maintian compatibility with any R engine implementation.
 The canonical way of obtaining a new engine is to call {@link #engineForClass}. All subclasses must implement createEngine() method. */
public abstract class REngine {
    /** last created engine or null if there is none */
    protected static REngine lastEngine = null;
	
    /** this is the designated constructor for REngine classes. It uses reflection to call createEngine method on the given REngine class.
	@param klass fully qualified class-name of a REngine implementation
	@return REngine implementation or null if createEngine invokation failed */
    public static REngine engineForClass(String klass) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, java.lang.reflect.InvocationTargetException {
		Class cl=Class.forName(klass);
		if (cl==null) throw(new ClassNotFoundException("can't find engine class "+klass));
		Method m=cl.getMethod("createEngine",(Class[])null);
		Object o=m.invoke(null,(Object[])null);
		return lastEngine=(REngine)o;
    }

	/** This is the extended constructor for REngine classes. It uses reflection to call createEngine method on the given REngine class with some additional control over the engine. Note that not all engines may support the extended version.
	 @param klass fully qualified class-name of a REngine implementation
	 @param args arguments to pass to R for initialization
	 @param callbacks delegate for REngine callbacks or null if callbacks won't be serviced (engine may not support callbacks)
	 @param runREPL if true then REPL will be started (if supported by the engine)
	 @return REngine implementation or null if createEngine invokation failed */
	public static REngine engineForClass(String klass, String[] args, REngineCallbacks callbacks, boolean runREPL) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, java.lang.reflect.InvocationTargetException {
		Class cl = Class.forName(klass);
		if (cl == null) throw new ClassNotFoundException("can't find engine class " + klass);
		Method m = cl.getMethod("createEngine", new Class[] { String[].class, REngineCallbacks.class, Boolean.TYPE });
		Object o = m.invoke(null, new Object[] { args, callbacks, new Boolean(runREPL) });
		return lastEngine = (REngine)o;
	}
	
    /** retrieve the last created engine
		@return last created engine or null if no engine was created yet */
    public static REngine getLastEngine() {
		return lastEngine;
    }

	/** parse a string into an expression vector
		@param text string to parse
		@param resolve resolve the resulting REXP (true) or just return a reference (false)
	    @return parsed expression */
	public abstract REXP parse(String text, boolean resolve) throws REngineException;

	/** evaluate an expression vector
		@param what an expression (or vector of such) to evaluate
		@param where environment to evaluate in (use null for the global environemnt and/or if environments are not supported by the engine)
		@param resolve resolve the resulting REXP or just return a reference
		@return the result of the evaluation of the last expression */
    public abstract REXP eval(REXP what, REXP where, boolean resolve) throws REngineException, REXPMismatchException;

	/** assign into an environment
		@param symbol symbol name
		@param value value to assign
		@param env environment to assign to (use null for the global environemnt and/or if environments are not supported by the engine) */
    public abstract void assign(String symbol, REXP value, REXP env) throws REngineException, REXPMismatchException;

	/** get a value from an environment
		@param symbol symbol name
		@param env environment (use null for the global environemnt and/or if environments are not supported by the engine)
		@param resolve resolve the resulting REXP or just return a reference		
		@return value */
    public abstract REXP get(String symbol, REXP env, boolean resolve) throws REngineException, REXPMismatchException;

	/** fetch the contents of the given reference. The resulting REXP may never be REXPReference. The engine should raise a {@link #REngineException} exception if {@link #supportsReferences()} returns false.
		@param ref reference to resolve
		@return resolved reference */
	public abstract REXP resolveReference(REXP ref) throws REngineException, REXPMismatchException;

	/** create a reference by pushing local data to R and returning a reference to the data. If ref is a reference it is returned as-is. The engine should raise a {@link #REngineException} exception if {@link #supportsReferences()} returns false.
	 @param value to create reference to
	 @return reference to the value */
	public abstract REXP createReference(REXP value) throws REngineException, REXPMismatchException;

	/** removes reference from the R side. This method is called automatically by the finalizer of REXPReference and should never be called directly.
	 @param ref reference to finalize */
	public abstract void finalizeReference(REXP ref) throws REngineException, REXPMismatchException;
	
	/** get the parent environemnt of an environemnt
	 @param env environment to query
	 @param resolve whether to resolve the resulting environment reference
	 @return parent environemnt of env */
	public abstract REXP getParentEnvironment(REXP env, boolean resolve) throws REngineException, REXPMismatchException;
	
	/** create a new environemnt
	 @param parent parent environment
	 @param resolve whether to resolve the reference to the environemnt (usually false since the returned environment will be empty)
	 @return resulting environment */
	public abstract REXP newEnvironment(REXP parent, boolean resolve) throws REngineException, REXPMismatchException;
	
    /** convenince method equivalent to eval(parse(text, false), where, resolve);
	 @param text to parse (see {@link #parse})
	 @param where environment to evaluate in (see {@link #eval})
	 @param resolve whether to resolve the resulting reference or not (see {@link #eval})
	 @return result */
	public REXP parseAndEval(String text, REXP where, boolean resolve) throws REngineException, REXPMismatchException {
		REXP p = parse(text, false);
		return eval(p, where, resolve);
	}

    /** convenince method equivalent to eval(parse(cmd, false), null, true);
	 @param cmd expression to parse (see {@link #parse})
	 @return result */
    public REXP parseAndEval(String cmd) throws REngineException, REXPMismatchException { return parseAndEval(cmd, null, true); };
	
	/** performs a close operation on engines that support it. The engine may not be used after close() returned true. This operation is optional and will always return false if not implemented.
	 @return true if the close opetaion was successful, false otherwise. */
	public boolean close() { return false; }
	
	//--- capabilities ---
	/** check whether this engine supports references to R objects
	 @return true if this engine supports references, false/code> otherwise */
	public boolean supportsReferences() { return false; }
	/** check whether this engine supports handing of environments (if not, {@link #eval} and {@link #assign} only support the global environment denoted by null).
	 @return true if this engine supports environments, false/code> otherwise */
	public boolean supportsEnvironments() { return false; }
	/** check whether this engine supports REPL (Read-Evaluate-Print-Loop) and corresponding callbacks.
	 @return true if this engine supports REPL, false/code> otherwise */
	public boolean supportsREPL() { return false; }
	/** check whether this engine supports locking ({@link #lock}, {@link #tryLock} and {@link #unlock}).
	 @return true if this engine supports REPL, false/code> otherwise */
	public boolean supportsLocking() { return false; }

	//--- convenience methods --- (the REXPMismatchException catches should be no-ops since the value type is guaranteed in the call to assign)
	/** convenience method equivalent to assign(symbol, new REXPDouble(d), null) (see {@link #assign(String, REXP, REXP)})
	 @param symbol symbol name to assign to
	 @param d values to assign */
	public void assign(String symbol, double[] d) throws REngineException { try { assign(symbol, new REXPDouble(d), null); } catch (REXPMismatchException e) { throw(new REngineException(this, "REXPMismatchException in assign(,double[]): "+e)); } }
	/** convenience method equivalent to assign(symbol, new REXPInteger(d), null) (see {@link #assign(String, REXP, REXP)})
	 @param symbol symbol name to assign to
	 @param d values to assign */
	public void assign(String symbol, int[] d) throws REngineException { try { assign(symbol, new REXPInteger(d), null); } catch (REXPMismatchException e) { throw(new REngineException(this, "REXPMismatchException in assign(,int[]): "+e)); } }
	/** convenience method equivalent to assign(symbol, new REXPString(d), null) (see {@link #assign(String, REXP, REXP)})
	 @param symbol symbol name to assign to
	 @param d values to assign */
	public void assign(String symbol, String[] d) throws REngineException { try { assign(symbol, new REXPString(d), null); } catch (REXPMismatchException e) { throw(new REngineException(this, "REXPMismatchException in assign(,String[]): "+e)); } }
	/** convenience method equivalent to assign(symbol, new REXPRaw(d), null) (see {@link #assign(String, REXP, REXP)})
	 @param symbol symbol name to assign to
	 @param d values to assign */
	public void assign(String symbol, byte[] d) throws REngineException { try { assign(symbol, new REXPRaw(d), null); } catch (REXPMismatchException e) { throw(new REngineException(this, "REXPMismatchException in assign(,byte[]): "+e)); } }
	/** convenience method equivalent to assign(symbol, new REXPString(d), null) (see {@link #assign(String, REXP, REXP)})
	 @param symbol symbol name to assign to
	 @param d value to assign */
	public void assign(String symbol, String d) throws REngineException { try { assign(symbol, new REXPString(d), null); } catch (REXPMismatchException e) { throw(new REngineException(this, "REXPMismatchException in assign(,String[]): "+e)); } }
	/** convenience method equivalent to assign(symbol, value, null) (see {@link #assign(String, REXP, REXP)})
	 @param symbol symbol name to assign to
	 @param value values to assign */
	public void assign(String symbol, REXP value) throws REngineException, REXPMismatchException { assign(symbol, value, null); }
	
	//--- locking API ---
	/** attempts to obtain a lock for this R engine synchronously (without waiting for it).
	    
Note: check for {@link #supportsLocking()} before relying on this capability. If not implemented, always returns 0.
	 @return 0 if the lock could not be obtained (R engine is busy) and some other value otherwise -- the returned value must be used in a matching call to {@link #unlock(int)}. */
	public synchronized int tryLock() { return 0; }

	/** obtains a lock for this R engine, waiting until it becomes available.
	 
Note: check for {@link #supportsLocking()} before relying on this capability. If not implemented, always returns 0.
	 @return value that must be passed to {@link #unlock} in order to release the lock */
	public synchronized int lock() { return 0; }

	/** releases a lock previously obtained by {@link #lock()} or {@link #tryLock()}.
	 
Note: check for {@link #supportsLocking()} before relying on this capability.  If not implemented, has no effect.
	 @param lockValue value returned by {@link #lock()} or {@link #tryLock()}. */	 
	public synchronized void unlock(int lockValue) {}

	public String toString() {
		return super.toString()+((lastEngine==this)?"{last}":"");
	}
	
	public REXP wrap(Object o){
		return REXPWrapper.wrap(o); 
	}
}