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 jsx.http.rpc.remote.client;
021 
022 import jsx.Returnable;
023 import jsx.http.rpc.remote.Callback;
024 import jsx.http.rpc.remote.Objective;
025 import jsx.http.rpc.remote.Reflector;
026 import jsx.http.rpc.remote.Remote;
027 
028 /**
029  * <p>A client reflection to basic Java arrays with the help of {@link Reflector}.</p>
030  * <p>Note that a object of this class is an {@link Objective} at client-side in that 
031  * when finalized it automatically tries to asynchronously dereference its server-side entity.</p>
032  * 
033  * @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>
034  */
035 public class CArray extends CObject
036 {
037     /**
038      * <p>The typical constructor for a {@link CArray} reflection.</p>
039      * @param reflector The {@link Reflector} object associated with the {@link CArray} object 
040      * being constructed.
041      * @param remote The underlying {@link Remote} object associated with the {@link CArray} 
042      * object being constructed.
043      * @since 1.0
044      */
045     protected CArray(Reflector reflector, Remote remote) {
046         super(reflector, remote);
047     }
048 
049     /**
050      * <p>Synchronously creates a {@link CArray} reflection from a {@link Remote} object 
051      * with a {@link Reflector}.</p>
052      * <p>This method synchronously increases server-side references to the {@link Remote} object.</p>
053      * @param reflector The {@link Reflector} object associated with the {@link CArray} object 
054      * being constructed.
055      * @param remote The underlying {@link Remote} object associated with the {@link CArray} 
056      * object being constructed.
057      * @return The created {@link CArray} reflection.
058      * @since 1.0
059      */
060     public static CArray create(Reflector reflector, Remote remote) {
061         reflector.increase(cat(remote));
062         return new CArray(reflector, remote);
063     }
064 
065     /**
066      * <p>Asynchronously creates a {@link CArray} reflection from a {@link Remote} object 
067      * with a {@link Reflector}.</p>
068      * <p>This method asynchronously increases server-side references to the {@link Remote} object.</p>
069      * @param reflector The {@link Reflector} object associated with the {@link CArray} object 
070      * being constructed.
071      * @param remote The underlying {@link Remote} object associated with the {@link CArray} 
072      * object being constructed.
073      * @param rt A {@link Returnable} to return the created {@link CArray} reflection.
074      * @since 1.0
075      */
076     public static void create(final Reflector reflector, final Remote remote, final Returnable<CArray> rt) {
077         reflector.increase(cat(remote), new Callback<Remote>() {
078             @Override
079             public void onCall(Remote ret) {
080                 rt.onReturn(new CArray(reflector, remote));
081             }
082         });
083     }
084 
085     /**
086      * <p>Synchronously gets the current length of the server-side array entity.</p>
087      * @return A {@link Remote} value of the current length of the server-side array entity.
088      * @since 1.0
089      */
090     public final Remote getLength() {
091         return reflector.getArrayLength(remote);
092     }
093 
094     /**
095      * <p>Asynchronously gets the current length of the server-side array entity.</p>
096      * @param rt A {@link Returnable} to return the {@link Remote} value of the current length 
097      * of the server-side array entity.
098      * @since 1.0
099      */
100     public final void getLength(final Returnable<Remote> rt) {
101         reflector.getArrayLength(remote, Callback.create(rt));
102     }
103 
104     /**
105      * <p>Synchronously gets an element of the server-side array entity.</p>
106      * @param i The array index of the element.
107      * @return A {@link Remote} value or object of the element.
108      * @since 1.0
109      */
110     public final Remote getElement(int i) {
111         return reflector.getArrayElement(remote, i);
112     }
113 
114     /**
115      * <p>Asynchronously gets an element of the server-side array entity.</p>
116      * @param i The array index of the element.
117      * @param rt A {@link Returnable} to return the {@link Remote} value or object of the element.
118      * @since 1.0
119      */
120     public final void getElement(final int i, final Returnable<Remote> rt) {
121         reflector.getArrayElement(remote, i, Callback.create(rt));
122     }
123 
124     /**
125      * <p>Synchronously sets an element of the server-side array entity.</p>
126      * @param i The array index of the element.
127      * @param v A {@link Remote} value or object for the element.
128      * @return The {@link Remote} value or object of the element.
129      * @since 1.0
130      */
131     public final Remote setElement(int i, Remote v) {
132         return reflector.setArrayElement(remote, i, v);
133     }
134 
135     /**
136      * <p>Asynchronously sets an element of the server-side array entity.</p>
137      * @param i The array index of the element.
138      * @param v A {@link Remote} value or object for the element.
139      * @param rt A {@link Returnable} to return the {@link Remote} value or object of the element.
140      * @since 1.0
141      */
142     public final void setElement(final int i, final Remote v, final Returnable<Remote> rt) {
143         reflector.setArrayElement(remote, i, v, Callback.create(rt));
144     }
145 
146     /**
147      * <p>Relays a given {@link Returnable} for asynchronous service of {@link Reflector}.</p>
148      * @param ref The associated {@link Reflector} object.
149      * @param rt The given {@link Returnable} to be relayed.
150      * @return The relaying {@link Returnable}.
151      * @since 1.0
152      */
153     public static Returnable<Remote> relay(final Reflector ref, final Returnable<CArray> rt) {
154         return new Returnable<Remote>() {
155             public void onReturn(Remote r) {
156                 create(ref, r, rt);
157             }
158         };
159     }
160 }