|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.rmi.server.RemoteObject
java.rmi.server.RemoteServer
java.rmi.server.UnicastRemoteObject
gnu.cajo.invoke.Remote
public final class Remote
This class takes any object, and allows it to be called from remote VMs. This class eliminates the need to maintain multiple specialised stubs for multiple, application specific objects. It effectively allows any object to be remoted, and makes all of the object's public methods, including its static ones, remotely callable. It also contains several very useful utility methods, to further support the invoke package paradigm.
It can also be run as an application, to load an object from a URL, and remote it within a JVM.
Field Summary | |
---|---|
java.lang.Object |
item
This is the reference to the local (or possibly remote) object reference being made remotely invokable by this Virtual Machine. |
Fields inherited from class java.rmi.server.RemoteObject |
---|
ref |
Constructor Summary | |
---|---|
Remote(java.lang.Object item)
The constructor takes any object, and allows it to be remotely invoked. |
|
Remote(java.lang.Object item,
int port,
java.rmi.server.RMIServerSocketFactory rssf,
java.rmi.server.RMIClientSocketFactory rcsf)
This constructor allows for complete configuration of an object's remoting; normally this should be used for rare and highly specialised cases. |
|
Remote(java.lang.Object item,
java.lang.String host,
int port)
The constructor takes any object, and allows it to be remotely invoked. |
Method Summary | |
---|---|
static java.lang.Class |
autobox(java.lang.Class arg)
This method emulates server Java5 argument autoboxing. |
Remote |
clientScope()
This method controls the automatic-unexporting of a remote reference when it is no longer referenced by any clients. |
static void |
config(int serverPort,
java.lang.String clientHost,
int clientPort,
java.lang.String proxyHost,
int proxyPort,
java.lang.String username,
java.lang.String password)
This method configures the server's TCP parameters for RMI through HTTP proxy servers. |
static void |
config(java.lang.String serverHost,
int serverPort,
java.lang.String clientHost,
int clientPort)
This method configures the server's TCP parameters for RMI. |
protected void |
finalize()
If the remote wrapper is being garbage collected, and it hasn't already been manually unexported, let's do that now, as a courtesy. |
static java.lang.reflect.Method |
findBestMethod(java.lang.Object item,
java.lang.String method,
java.lang.Class[] args)
This method attempts to resolve the argument inheritance blindness in Java reflection-based method selection. |
static java.lang.String |
getDefaultClientHost()
This is the default server network address on which left unspecified, clients connect to remoted items. |
static int |
getDefaultClientPort()
This is the default server host port on which left unspecified, items are being remoted. |
static java.rmi.server.RMIClientSocketFactory |
getDefaultClientSocketFactory()
This is the default RMIClientSocketFactory on which left unspecified, items are being remoted. |
static java.lang.String |
getDefaultServerHost()
This is the default server host address on which left unspecified, items are being remoted. |
static int |
getDefaultServerPort()
This is the default client port on which left unspecified, items are being remoted. |
static java.rmi.server.RMIServerSocketFactory |
getDefaultServerSocketFactory()
This is the default RMIServerSocketFactory on which left unspecified, items are being remoted. |
static java.lang.Object |
getItem(java.lang.String url)
A utility method to load either an item, or a zipped marshalled object (zedmob) of an item, from a URL, file, or from a remote rmiregistry. |
static java.lang.Object |
invoke(java.lang.Object item,
java.lang.String method,
java.lang.Object args)
This function may be called reentrantly, so the item object must synchronize its critical sections as necessary. |
java.lang.Object |
invoke(java.lang.String method,
java.lang.Object args)
The sole generic, multi-purpose interface for communication between VMs. |
static void |
main(java.lang.String[] args)
The application method loads a zipped marshalled object (zedmob) from a URL, or a file, and allows it run in this virtual machine. |
java.lang.Object |
send(java.lang.String url)
This method sends its remote reference to another item, either from a URL, file, or from a remote rmiregistry. |
static void |
shutdown()
This method will brutally un-remote all currently remotely invocable wrappers, except those in clientScope. |
boolean |
unexport(boolean force)
This method will attempt to make the wrapper no longer remotely invocable. |
void |
unreferenced()
This method is called by the RMI runtime after it determines the there are no pending invocations on the wrapper. |
static java.lang.Object |
zedmob(java.io.InputStream is)
A utility method to reconstitute a zipped marshalled object (zedmob) into a remote item reference, proxy object, or local object. |
void |
zedmob(java.io.OutputStream os)
This method will write this remote item reference to an output stream as a zipped marshalled object (zedmob). |
static void |
zedmob(java.io.OutputStream os,
java.lang.Object ref)
This method will write the local item, remote item reference, or proxy, to an output stream as a zipped marshalled object (zedmob). |
Methods inherited from class java.rmi.server.UnicastRemoteObject |
---|
clone, exportObject, exportObject, exportObject, unexportObject |
Methods inherited from class java.rmi.server.RemoteServer |
---|
getClientHost, getLog, setLog |
Methods inherited from class java.rmi.server.RemoteObject |
---|
equals, getRef, hashCode, toString, toStub |
Methods inherited from class java.lang.Object |
---|
getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public final java.lang.Object item
Constructor Detail |
---|
public Remote(java.lang.Object item) throws java.rmi.RemoteException
Invoke
interface,
it will route all remote invocations directly to it. Otherwise it will
use Java reflection to attempt to invoke the remote calls directly on
the object's public methods.
item
- The object to make remotely callable. It may be an
arbitrary object of any type, it can even be a reference to a remote
reference from another host, being re-remoted through this JVM.
RemoteExcepiton
- If the remote instance could not be be created.
java.rmi.RemoteException
public Remote(java.lang.Object item, java.lang.String host, int port) throws java.rmi.RemoteException
Invoke
interface,
it will route all remote invocations directly to it. Otherwise it will
use Java reflection to attempt to invoke the remote calls directly on
the object's public methods.
item
- The object to make remotely callable. It may be an
arbitrary object of any type, it can even be a reference to a remote
reference from another host, being re-remoted through this JVM.host
- The network interface on which clients will communicate
with this item. It is typically specified when clients have more than
one.port
- The TCP port over which the server and client will communicate
RemoteExcepiton
- If the remote instance could not be be created.
java.rmi.RemoteException
public Remote(java.lang.Object item, int port, java.rmi.server.RMIServerSocketFactory rssf, java.rmi.server.RMIClientSocketFactory rcsf) throws java.rmi.RemoteException
item
- The object to make remotely callable. It may be an
arbitrary object of any type, it can even be a reference to a remote
reference from another host, being re-remoted through this JVM.port
- The server TCP port number on which the server will
be operating.rcsf
- The custom client socket factory to be used to communicate
with this item, by remote clients. (please regard carefully the note
above)rssf
- The custom server socket factory to be used to accept
connections from remote clients.
RemoteExcepiton
- If the remote instance could not be be created.
java.rmi.RemoteException
Method Detail |
---|
protected void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
- due to Object class method definition, this method
will throw nothingpublic static java.rmi.server.RMIServerSocketFactory getDefaultServerSocketFactory()
public static java.rmi.server.RMIClientSocketFactory getDefaultClientSocketFactory()
public static java.lang.String getDefaultServerHost()
public static int getDefaultServerPort()
public static java.lang.String getDefaultClientHost()
public static int getDefaultClientPort()
public static void config(java.lang.String serverHost, int serverPort, java.lang.String clientHost, int clientPort)
Note: If this class is to be specifically configured, it must be done before any items are remoted. It can be called only one time, any subsequent calls will result in an IllegalArgumentException being thrown.
serverHost
- The local network interface on which the item will
will be remotely invokable. Typically it is specified when the server
has multiple phyisical network interfaces, or is multi-homed, i.e.
having multiple logical network interfaces. The value can be null,
which will make the item accessible on all network interfaces,
this is identical to providing the special port address "0.0.0.0".serverPort
- Specifies the local port on which the server is
serving clients. It can be zero, to use an anonymous port. If firewalls
are being used, it must be an accessible port, into this server. If this
port is zero, and the ClientPort argument is non-zero, then the
ClientPort value will automatically substituted.clientHost
- The host name, or IP address the remote client will
use to communicate with this server. If null, it will be the same as
serverHost resolution. This would need to be explicitly specified if
the server is operating behind NAT; i.e. when the server's subnet IP
address is not the same as its address outside the subnet.clientPort
- Specifies the particular port on which the client
will connect to the server. Typically this is the same number
as the serverPort argument, but could be different, if port translation
is being used. If the clientPort field is 0, i.e. anonymous, its port
value will be automatically assigned to match the server, even if the
server port is also anonymous.public static void config(int serverPort, java.lang.String clientHost, int clientPort, java.lang.String proxyHost, int proxyPort, java.lang.String username, java.lang.String password)
Note: If this class is to be configured, it must be done before any items are remoted.
serverPort
- Specifies the local port on which the server is
serving clients. It can be zero, to use an anonymous port. If firewalls
are being used, it must be an accessible port, into this server. If this
port is zero, and the ClientPort argument is non-zero, then the
ClientPort value will automatically substituted.clientHost
- The host name, or IP address the remote client will
use to communicate with this server. If null, it will be the same as
serverHost resolution. This would need to be explicitly specified if
the server is operating behind NAT; i.e. when the server's subnet IP
address is not the same as its address outside the subnet.clientPort
- Specifies the particular port on which the client
will connect to the server. Typically this is the same number
as the serverPort argument, but could be different, if port translation
is being used. If the clientPort field is 0, i.e. anonymous, its port
value will be automatically assigned to match the server, even if theproxyHost
- The name or address of the proxy server used to gain
HTTP access to the internet.proxyPort
- The port number of the proxy server used to gain
HTTP access to the internet.username
- The proxy account user name required for permission, if
non-null.password
- The proxy account password required for permission, if
non-null.public static void shutdown()
public static java.lang.Object zedmob(java.io.InputStream is) throws java.lang.ClassNotFoundException, java.io.IOException
Note: on completion of reading the item from the stream, the stream will be automatically closed.
is
- The input stream containing the zedmob of the item reference.
java.io.IOException
- if the zedmob format is invalid.
java.lang.ClassNotFoundException
- if a proxy object was sent, and remote
class loading was not enabled in this VM.public static void zedmob(java.io.OutputStream os, java.lang.Object ref) throws java.io.IOException
Note: on completion of writing the item, or reference, the stream will be closed. Typically, when saved to a file, a zedmob has the file extension .zmob to provide obvious identification.
os
- The output stream on which to write the reference. It may be
a file stream, a socket stream, or any other type of stream.ref
- The item or reference to be serialized.
java.io.IOException
- For any stream related writing error.public static java.lang.Object getItem(java.lang.String url) throws java.rmi.RemoteException, java.rmi.NotBoundException, java.io.IOException, java.lang.ClassNotFoundException, java.lang.InstantiationException, java.lang.IllegalAccessException, java.net.MalformedURLException
Loading an item from a file can be specified in one of three ways:
File loading will first be attempted from within the server's jar file, if that fails, it will then look in the local filesystem.
Note: any socket connections made by the incoming item cannot be known at compile time, therefore proper operation if this VM is behind a firewall could be blocked. Use behind a firewall would require knowing all the ports that would be needed in advance, and enabling them before loading the proxy.
url
- The URL where to get the object: file://, http://, ftp://,
/path/name, path/name, or //[host][:port]/[name]. The host, port,
and name, are all optional. If missing the host is presumed local, the
port 1099, and the name "main". The referenced resource can be
returned as a MarshalledObject, it will be extracted automatically.
If the URL is null, it will be assumed to be ///.
java.rmi.RemoteException
- if the remote registry could not be reached.
java.rmi.NotBoundException
- if the requested name is not in the registry.
java.io.IOException
- if the zedmob format is invalid.
java.lang.ClassNotFoundException
- if a proxy was sent to the VM, and
proxy hosting was not enabled.
java.lang.InstantiationException
- when the URL specifies a class name
which cannot be instantiated at runtime.
java.lang.IllegalAccessException
- when the url specifies a class name
and it does not support a no-arg constructor.
java.net.MalformedURLException
- if the URL is not in the format explainedpublic static java.lang.Class autobox(java.lang.Class arg)
findBestMethod
. This technique has been most
graciously championed by project member Zac Wolfe. It allows
public server methods to use primitive types for arguments, and
return values.
arg
- The the argument class to test for boxing. If the argument
type is primitive, it will be substituted with the corresponding
primitive class representation.
public static java.lang.reflect.Method findBestMethod(java.lang.Object item, java.lang.String method, java.lang.Class[] args)
item
- The object on which to find the most applicable public
method.method
- The name of the method, which is to be invoked.args
- The class representations of the arguments to be
provided to the method, it can be either null or length 0, if the
method takes no arguments
public static java.lang.Object invoke(java.lang.Object item, java.lang.String method, java.lang.Object args) throws java.lang.Exception
item
- The object on which to invoke the method. If the item
implements the Invoke
interface, the call will be passed
directly to it.method
- The method name to be invoked.args
- The arguments to provide to the method for its invocation.
TransparentItemProxy
,
implementing all of the interfaces of the return object instance.
java.lang.IllegalArgumentException
- If the method argument is null.
java.lang.NoSuchMethodException
- If no matching method can be found.
java.lang.Exception
- If the item rejected the invocation, for application
specific reasons. The cause of the exception will be automatically
unpacked from an internally resulting
java.lang.reflect.InvocationTargetException, to provide the calling
code with the actual exception resulting from the method invocation.
Special thanks to Petr Stepan for pointing out this improvement, and
providing a
link to the discussion.public boolean unexport(boolean force) throws java.rmi.NoSuchObjectException
force
- true to un-remote the object wrapper, even if invocations
are in progress or pending, if false, do not un-remote unless idle.
java.rmi.NoSuchObjectException
- If this wrapper has already been
un-remotedpublic java.lang.Object invoke(java.lang.String method, java.lang.Object args) throws java.lang.Exception
invoke
in interface Invoke
method
- The method to invoke on the internal object.args
- The arguments to provide to the method for its invocation.
It can be a single object, an array of objects, or even null.
java.rmi.RemoteException
- For network communication related
reasons.
java.lang.IllegalArgumentException
- If reflection is going to be used,
and the method argument is null.
java.lang.NoSuchMethodException
- If no matching method can be found.
java.lang.Exception
- If the internal item rejected the invocation, for
application specific reasons.public java.lang.Object send(java.lang.String url) throws java.lang.Exception
getItem
method to obtain a reference to the remote
item. It will next invoke the received reference's invoke method with
a "send" value, and a reference to itself as its sole argument.
url
- The URL where to get the remote host interface: file://,
http://, ftp://, /path/name, path/name, or //[host][:port]/[name].
The host, port, and name, are all optional. If missing the host is
presumed local, the port 1099, and the name "main". If the URL is
null, it will be assumed to be ///.
java.lang.Exception
- Either from the getItem invocation, or if the
item reference invocation fails.public void zedmob(java.io.OutputStream os) throws java.io.IOException
os
- The output stream on which to write the reference. It may be
a file stream, a socket stream, or any other type of stream.
java.io.IOException
- For any stream related writing error.public void unreferenced()
unreferenced
in interface java.rmi.server.Unreferenced
public Remote clientScope()
return new Remote(tempObj).clientScope();
public static void main(java.lang.String[] args) throws java.lang.Exception
getItem
method to load the item. Following loading
of the item, it will also create an rmiregistry, and bind a remote
reference to it under the name "main". This will also allow remote
clients to connect to, and interact with it.Note:It will require a security policy, to define what permissions the loaded item will be allowed. There are six optional configuration parameters:
java.lang.Exception
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |