BiVariable.java

  1. /**
  2.  * **** BEGIN LICENSE BLOCK *****
  3.  * Version: EPL 1.0/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Eclipse Public
  6.  * License Version 1.0 (the "License"); you may not use this file
  7.  * except in compliance with the License. You may obtain a copy of
  8.  * the License at http://www.eclipse.org/legal/epl-v10.html
  9.  *
  10.  * Software distributed under the License is distributed on an "AS
  11.  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  12.  * implied. See the License for the specific language governing
  13.  * rights and limitations under the License.
  14.  *
  15.  * Copyright (C) 2009-2011 Yoko Harada <yokolet@gmail.com>
  16.  *
  17.  * Alternatively, the contents of this file may be used under the terms of
  18.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  19.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  20.  * in which case the provisions of the GPL or the LGPL are applicable instead
  21.  * of those above. If you wish to allow use of your version of this file only
  22.  * under the terms of either the GPL or the LGPL, and not to allow others to
  23.  * use your version of this file under the terms of the EPL, indicate your
  24.  * decision by deleting the provisions above and replace them with the notice
  25.  * and other provisions required by the GPL or the LGPL. If you do not delete
  26.  * the provisions above, a recipient may use your version of this file under
  27.  * the terms of any one of the EPL, the GPL or the LGPL.
  28.  * **** END LICENSE BLOCK *****
  29.  */
  30. package org.jruby.embed.variable;

  31. import org.jruby.Ruby;
  32. import org.jruby.RubyObject;
  33. import org.jruby.runtime.builtin.IRubyObject;

  34. /**
  35.  * Represents bidirectional, both Java and Ruby, variables. Users don't instantiate
  36.  * BiVariable type objects. Instead, users can get this type object from
  37.  * {@link BiVariableMap} after a variable is set to the map. Users can set variables
  38.  * in Java program explicitly through put() methods in {@link ScriptingContainer}
  39.  * and {@link BiVariableMap} or equivalents. However, variables in Ruby scripts are
  40.  * set in the map implicitly. When variables and constants
  41.  * are used in the script, those are automatically saved in the map converting to this type.
  42.  *
  43.  * @author Yoko Harada <yokolet@gmail.com>
  44.  */
  45. public interface BiVariable {
  46.     /**
  47.      * Defines a type correspond to Ruby's variables and constant types.
  48.      */
  49.     public enum Type {
  50.         Argv, Constant, GlobalVariable, LocalGlobalVariable, ClassVariable, InstanceVariable, LocalVariable
  51.     }

  52.     /**
  53.      * Returns one of the Ruby's variables or constant types defined by Type.
  54.      *
  55.      * @return a type that corresponds to Ruby's variables and constant types.
  56.      */
  57.     public Type getType();

  58.     /**
  59.      * Returns the original receiver where this variable has been retrieved.
  60.      *
  61.      * @return an original receiver.
  62.      */
  63.     public IRubyObject getReceiver();

  64.    /**
  65.      * Returns true if a given receiver is identical to the receiver this object has.
  66.      *
  67.      * @return true if identical otherwise false.
  68.      */
  69.     public boolean isReceiverIdentical(RubyObject receiver);

  70.     /**
  71.      * Returns a name of the variable this object holds. The name follows Ruby's
  72.      * naming rule.
  73.      *
  74.      * @return a name of the variable
  75.      */
  76.     public String getName();

  77.     /**
  78.      * Returns a value of the variable this object holds in Java type.
  79.      *
  80.      * @return a value in Java type.
  81.      */
  82.     public Object getJavaObject();

  83.     /**
  84.      * Sets a Java object as a value of this object. At the same time,
  85.      * an equivalent Ruby object is set automatically.
  86.      *
  87.      * @param runtime is used to convert a Java object to Ruby object.
  88.      * @param javaObject is a variable value to be set.
  89.      */
  90.     public void setJavaObject(Ruby runtime, Object javaObject);

  91.     /**
  92.      * Injects a variable value to a parsed Ruby script. This method is invoked
  93.      * during EvalUnit#run() is executed. Users don't use this method.
  94.      */
  95.     public void inject();

  96.     /**
  97.      * Returns a value of the variable this object holds in
  98.      * a org.jruby.runtime.builtin.IRubyObject type.
  99.      *
  100.      * @return a value in IRubyObject type.
  101.      */
  102.     public IRubyObject getRubyObject();

  103.     /**
  104.      * Sets a org.jruby.runtime.builtin.IRubyObject type, Ruby object as a value
  105.      * of this object. At the same time, an equivalent Java object is set automatically.
  106.      *
  107.      * @param runtime is environment where a variable injection occurs
  108.      * @param rubyObject is a variable value to be set.
  109.      */
  110.     public void setRubyObject(IRubyObject rubyObject);

  111.     /**
  112.      * Attempts to remove this variable/constant from top self or receiver.
  113.      *
  114.      */
  115.     public void remove();
  116. }