001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js;
021 
022 /**
023  * <p>An <b>opaque</b> interface representing LiveConnet Java objects of JavaScript.</p>
024  * <p>This interface must be implemented in JS Simulation Libraries.</p>
025  *
026  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
027  * @see Js#connect(Object)
028  * @see Js#connect(String, String)
029  * @see LiveClass
030  * 
031  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be 
032  * generated into the target codes. Re-compilers must exit with error on the operations of 
033  * accessing that kind of class objects.
034  */
035 
036 public interface LiveObject
037 {
038     /**
039      * <p>Gets a instance field of the current LiveConnect Java object.</p>
040      * @param fld The name of the field to get.
041      * @return The value of the field.
042      * @since 1.0
043      * @javascript Re-compilers must convert the interface invocation of this method into the 
044      * JavaScript expression: 
045      * <pre>o.fld</pre>
046      * where <tt>o</tt> is the current instance of the invocation of this method and 
047      * <tt>fld</tt> must be resolved to the property identifier at the re-compile time.
048      */
049     public Object get(String fld);
050     /**
051      * <p>Sets value to an instance field of the current LiveConnect Java object.</p>
052      * @param fld The name of the field to set value to.
053      * @param val The new value to be set to the field.
054      * @return The new value set to the field.
055      * @since 1.0
056      * @javascript Re-compilers must convert the interface invocation of this method into the 
057      * JavaScript expression: 
058      * <pre>(o.fld = val)</pre> 
059      * where <tt>o</tt> is the current instance of the invocation of this method and 
060      * <tt>fld</tt> must be resolved to the property identifier at the re-compile time.
061      */
062     public Object set(String fld, Object val);
063     /**
064      * <p>Returns the string representation of the current LiveConnect Java object.</p>
065      * @return The string representation of the current LiveConnect Java object.
066      * @see #valueOf()
067      * @since 1.0
068      * @javascript Re-compilers must convert the interface invocation of this method directly 
069      * into a JavaScript invocation on its current array instance without changing the 
070      * method name, but expanding variable arguments, if any, into comma-separated values. 
071      */
072     public String toString();
073     /**
074      * <p>Returns the primitive value associated with the current instance, if there is one.</p>
075      * @return The current LiveConnect Java object itself.
076      * @see #toString()
077      * @since 1.0
078      * @javascript Re-compilers must convert the interface invocation of this method directly 
079      * into a JavaScript invocation on its current array instance without changing the 
080      * method name, but expanding variable arguments, if any, into comma-separated values. 
081      */
082     public Object valueOf();
083     /**
084      * <p>Invokes an instance method of the current LiveConnect Java object.</p>
085      * @param met The name of the instance method to invoke.
086      * @since 1.0
087      * @javascript Re-compilers must convert the interface invocation of this method into the 
088      * JavaScript expression: 
089      * <pre>o.met()</pre> 
090      * where <tt>o</tt> is the current instance of the invocation of this method and 
091      * <tt>met</tt> must be resolved to the method identifier at the re-compile time.
092      */
093     public void run(String met);
094     /**
095      * <p>Invokes an instance method of the current LiveConnect Java object with an argument.</p>
096      * @param met The name of the instance method to invoke.
097      * @param atype The type descriptor of the argument <tt>arg</tt>. This argument 
098      * is ignored by JS Re-compilers.
099      * @param arg The argument for the invocation.
100      * @since 1.0
101      * @javascript Re-compilers must convert the interface invocation of this method into the 
102      * JavaScript expression: 
103      * <pre>o.met(arg)</pre> 
104      * where <tt>o</tt> is the current instance of the invocation of this method and 
105      * <tt>met</tt> must be resolved to the method identifier at the re-compile time.
106      */
107     public void run(String met, String atype, Object arg);
108     /**
109      * <p>Invokes an instance method of the current LiveConnect Java class with a variable 
110      * arguments list.</p>
111      * @param met The name of the instance method to invoke.
112      * @param atypes The type descriptors of the variable argument list <tt>args</tt>. This 
113      * argument is ignored by JS Re-compilers.
114      * @param args The variable argument list for the invocation.
115      * @since 1.0
116      * @javascript Re-compilers must convert the interface invocation of this method into the 
117      * JavaScript expression: 
118      * <pre>o.met(args)</pre> 
119      * where <tt>o</tt> is the current instance of the invocation of this method and 
120      * <tt>met</tt> must be resolved to the method identifier at the re-compile time and 
121      * <tt>args</tt> must be expanded into comma-separated arguments at the re-compile 
122      * time .
123      */
124     public void run(String met, Vars<String> atypes, Vars<?> args);
125     /**
126      * <p>Calls an instance method of the current LiveConnect Java object.</p>
127      * @param met The name of the instance method to call.
128      * @return The return value of the invocation.
129      * @since 1.0
130      * @javascript Re-compilers must convert the interface invocation of this method into the 
131      * JavaScript expression: 
132      * <pre>o.met()</pre> 
133      * where <tt>o</tt> is the current instance of the invocation of this method and 
134      * <tt>met</tt> must be resolved to the method identifier at the re-compile time.
135      */
136     public Object call(String met);
137     /**
138      * <p>Calls an instance method of the current LiveConnect Java object with an argument.</p>
139      * @param met The name of the instance method to call.
140      * @param atype The type descriptor of the argument <tt>arg</tt>. This argument is 
141      * ignored by JS Re-compilers.
142      * @param arg The argument for the invocation.
143      * @return The return value of the invocation.
144      * @since 1.0
145      * @javascript Re-compilers must convert the interface invocation of this method into the 
146      * JavaScript expression: 
147      * <pre>o.met()</pre> 
148      * where <tt>o</tt> is the current instance of the invocation of this method and 
149      * <tt>met</tt> must be resolved to the method identifier at the re-compile time.
150      */
151     public Object call(String met, String atype, Object arg);
152     /**
153      * <p>Calls an instance method of the current LiveConnect Java object with a variable 
154      * arguments list.</p>
155      * @param met The name of the instance method to call.
156      * @param atypes The type descriptors of the variable argument list <tt>args</tt>.
157      * This argument is ignored by JS Re-compilers.
158      * @param args The variable argument list for the invocation.
159      * @return The return value of the invocation.
160      * @since 1.0
161      * @javascript Re-compilers must convert the interface invocation of this method into the 
162      * JavaScript expression: 
163      * <pre>o.met(args)</pre> 
164      * where <tt>o</tt> is the current instance of the invocation of this method and 
165      * <tt>met</tt> must be resolved to the method identifier at the re-compile time and 
166      * <tt>args</tt> must be expanded into comma-separated arguments at the re-compile 
167      * time.
168      */
169     public Object call(String met, Vars<String> atypes, Vars<?> args);
170     /**
171      * <p>Gets the LiveConnect Java class of the current LiveConnect Java object.</p>
172      * @return The LiveConnect Java class of the current LiveConnect Java object.
173      * @since 1.0
174      * @javascript Re-compilers must convert the interface invocation of this method into the 
175      * JavaScript expression: 
176      * <pre>o.getClass()</pre> 
177      * where <tt>o</tt> is the current instance of the invocation of this method.
178      */
179     public LiveClass getJavaClass();
180 }