Client-side Invocation
http://plover.sourceforge.net \| Last published: 03 April, 2005

Executive Summary

Home

Overview

License

Download

Project Summary

Change Notes

Using Plover

Installation

Configuration

Hosted Entities

Client-side Invocation

Network Discovery

API Documentation

This project is hosted on

Integration

Plover defines a client-side invocation environment for method invocation on server-side hosted entities. This environment, called the Plover Invoker, encapsulates low-level operational details and provides communication transparency to high-level application logic.

Download and extract the contents of plover-invoker-0.2.0.zip into a suitable folder on your local machine. Ensure that the extracted jar files are available as entries in the application classpath.

An Example Invocation

Let us now implement a client-side invocation logic for the user manager entity example introduced in Hosted Entities section. We will start by defining a Java interface whose methods correspond to those of the remotely accessible user manager entity.




public interface IUserManager

{

    public void addUser(UserData data) throws UserException;



    public void updateUser(UserData data) throws UserException;



    public void deleteUser(String userName) throws UserException;

}

Please note the following important points with respect to the client-side invocation definition:

The client-side invocation definition must always be an interface.
There are no naming conventions for the interface being defined. Nor are there any specific interfaces to be extended.
The client side definition can have a different footprint (number of methods and their signatures) from that of its hosted entity. This will not result in a compilation error. However, at runtime, invoking interface methods that does not have an exact signature match with those of the hosted entity will result in a runtime error.

The following code example shows how you can bind the client-side invocation interface with the Plover invoker and call methods on the same from within the client application logic.




import omd.plover.invoker.*;



...

InvokerFactory factory = new InvokerFactory();

IPloverInvoker invoker = factory.getInvoker("rmi://somehost/plover");

IUserManager usrMgr = (IUserManager)

        invoker.register("userMgr", IUserManager.class);

usrMgr.addUser(usrData);

...

In this example, we use the invoker factory to create an instance of Plover invoker that will use RMI as the transport mechanism to connect to the hosting environment on machine somehost. In addition, the hosting environment is configured to have the RMI transport enabled with default values.

Register the invocation definition against a given identifier with the invoker. The identifier must be same as that used to bind the server-side entity with the hosting environment. The invoker returns a generic object that implements the definition interface. A method call on the typecasted form of this object results in the corresponding method being invoked on the hosted entity.

Additional Invoker Forms

The following code example shows how to create a Plover invoker that uses HTTP as the transport mechanism.




InvokerFactory factory = new InvokerFactory();

IPloverInvoker invoker = factory.getInvoker("http://somehost/plover");

The hosting environment is embedded within a servlet container that is running on the machine somehost on port 80 (the default HTTP port). The Plover servlet is configured to be aliased against the path /plover in the web-application assembly descriptor.

In most cases, the communication mechanism will require additional information other than what is provided as part of the connection string. You will need to encapsulate such information in a java.util.Properties object and use the additional factory method as shown below.




Properties connProps = new Properties();

// Fill in additional information.

...



InvokerFactory factory = new InvokerFactory();

IPloverInvoker invoker

  = factory.getInvoker("http://somehost/plover", connProps);

The following keys define the extra information that can be passed using the properties object. Note that key names are case-sensitive.

auth.username The user name for authetication and access control. This is common for both RMI and HTTP transports.

auth.password The password for authetication and access control. This is common for both RMI and HTTP transports.

proxy.host Network address of the proxy server. This is required only for HTTP transport where the client system is behind a proxy-based firewall.

proxy.port Port number of the proxy server. This is required only for HTTP transport where the client system is behind a proxy-based firewall.