refcodes-remoting: Face-to-face lightweight remote method calls

README

The REFCODES.ORG codes represent a group of artifacts consolidating parts of my work in the past years. Several topics are covered which I consider useful for you, programmers, developers and software engineers.

What is this repository for?

This artifact is a lightweight RPC (remote procedure call) toolkit (you may also call it an IPC (inter process communication) toolkit). On your server you publish any instance (any Java object), on your client you may access this instance via a proxy object which looks and feels exactly as the remote instance on the server.

How do I get set up?

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1
2
3
4
5
6
7
8
9
<dependencies>
	...
	<dependency>
		<artifactId>refcodes-remoting</artifactId>
		<groupId>org.refcodes</groupId>
		<version>3.3.8</version>
	</dependency>
	...
</dependencies>

The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at javadoc.io.

Introduction

Publish an instance (just any Java object) on your server, connect to it on your client via a proxy - voilà, you may do remote method calls via the proxy on the instance … just with a few lines of code …

This proxy provides your client exactly the same methods as the instance offers on the server. Invoking any of them methods on the proxy at the client actually causes the according method on the remote instance at the server to be processed. Voilà, there is your remote procedure call!

Neither stubs nor skeletons to be generated anywhere, no need for you to generate any code.

This toolkit can be attached to virtually any kind of connection (implement your own):

Loopback connection: Direct object access on the same JVM (see LoopbackRemoteTest source codes)
Input-/OutputStream: Anything which is a Java InputStream/OutputStream can be used (see IoStreamRemoteTest source codes)
Socket: Use Java’s ServerSocket / (Client-)Socket mechanism (see ObservableSocketRemoteTest source codes)

The refcodes-remoting-ext-observer provides an observable implementation (as of the refcodes-observer artifact) of the refcodes-remoting tool-box.

Yes, it’s observable: You get events when a client subscribes (you may veto the subscription in your listener) to an instance on your server or when it unsubscribes.

How do I get started?

First setup your server; we start off with a socket based example; using streams is even simpler. Create your server and publish the object you’d like to be invoked remote by a client:

1
2
3
4
5
...
List<String> theServerList = new ArrayList<String>();
RemoteServer theServer = new RemoteServer();
theServer.publishSubject( theServerList );
...

Then you wait for your client to connect to your ServerSocket. From the Socket created upon connection you create an PrefetchBidirectionalStreamConnectionTransceiver which is used to open your Server:

1
2
3
4
5
6
7
...
ServerSocket theServerSocket = new ServerSocket( 5161 );
Socket theSocket = theServerSocket.accept();
PrefetchBidirectionalStreamConnectionTransceiver<Serializable> theServerTransceiver = new PrefetchBidirectionalStreamConnectionTransceiver<Serializable>();
theServerTransceiver.open( theSocket.getInputStream(), theSocket.getOutputStream() );
theServer.open( theServerTransceiver );
...

Next you setup your client. You create a Socket to your server from which you produce an PrefetchBidirectionalStreamConnectionTransceiver which is used to open your Client

1
2
3
4
5
6
7
...
RemoteClient theClient = new RemoteClient();
Socket theClientSocket = new Socket( "localhost", 5161 );
PrefetchBidirectionalStreamConnectionTransceiver<Serializable> theClientTransceiver = new PrefetchBidirectionalStreamConnectionTransceiver<Serializable>();
theClientTransceiver.open( theClientSocket.getInputStream(), theClientSocket.getOutputStream() );
theClient.open( theClientTransceiver );
...

Snippets of interest

Below find some code snippets which demonstrate the various aspects of using the refcodes-remoting artifact (and , if applicable, its offsprings). See also the example source codes of this artifact for further information on the usage of this artifact.

Access remote instances

Having prepared your setup as above, you now can invoke the methods provided by the theServerList on your client by retrieving the according proxy:

1
2
3
4
5
...
if ( theClient.hasProxy( List.class ) ) {
	List<?> theProxyList = theClient.getProxy( List.class );
}
...

Determine available remote instances

You may also list all published remote instances:

1
2
3
4
5
...
for( Object eProxy: theClientRemote.proxies().next() {
	System.out.println( "Remote instance = " + eProxy );
}
...

Examples

Please refer to the example source code (as well as this example source code) for more examples on the usage of this artifact.

The above examples are tweaked to run as unit tests on a single machine!

Contribution guidelines

Report issues
Finding bugs
Helping fixing bugs
Making code and documentation better
Enhance the code

Who do I talk to?

Siegfried Steiner (steiner@refcodes.org)

Terms and conditions

The REFCODES.ORG group of artifacts is published under some open source licenses; covered by the refcodes-licensing (org.refcodes group) artifact - evident in each artifact in question as of the pom.xml dependency included in such artifact.

refcodes-remoting: Face-to-face lightweight remote method calls

Categories

Tags