Chapter 2. Central concepts

Remoting is based on the client server model, and communication between a client and a server is handled by one of Remoting's several transports. A transport is characterized by a pair of classes, one for the client side and one for the server side, which communicate by a shared protocol. Most of the core concepts discussed below are related to one side or the other. However, the URL, or the internal object used to represent the URL, of a server is relevant to both sides.

2.1. Server side concepts

  • org.jboss.remoting.ServerInvocationHandler:

    is a server side object that incorporates application logic. A ServerInvocationHandler may be associated with a particular subsystem, specified by an arbitrary string. For example, JBoss Messaging uses "JMS".

  • org.jboss.remoting.ServerInvoker:

    is the server side object that fields invocations and passes them to the appropriate ServerInvocationHandler. Each of EJB2, EJB3, and JBoss Messaging have their own ServerInvocationHandlers. ServerInvoker is subclassed for each transport; e.g., org.jboss.remoting.transport.socket.SocketServerInvoker, org.jboss.remoting.transport.bisocket.BisocketServerInvoker, etc.

  • org.jboss.remoting.transport.Connector:

    is the external face of the ServerInvoker, by which the ServerInvoker is configured declaratively. The configuration includes a designated transport, ServerInvoker parameters, and one or more ServerInvocationHandler classes.

2.2. Client side concepts

  • org.jboss.remoting.RemoteClientInvoker:

    is a client side object corresponding to a particular ServerInvoker. It is responsible for marshalling an invocation to the wire and unmarshalling the response. Each RemoteClientInvoker is subclassed for each transport; e.g., org.jboss.remoting.transport.socket.SocketClientInvoker, org.jboss.remoting.transport.bisocket.BisocketClientInvoker, etc.

  • org.jboss.remoting.Client:

    is the conduit between application code and the RemoteClientInvoker. Multiple Clients can share a single RemoteClientInvoker if they have the same InvokerLocator and the same set of configuration parameters. In a pure Remoting application, the application code would be responsible for creating the Client(s). However, in the context of the Application Server, Clients and RemoteClientInvokers are hidden below the surface. For example, a JBoss Messaging producer or consumer creates one or more Clients. In EJB2 and EJB3, Clients are create by an interceptor embedded in an object which is retrieved from the server side. In these cases, JBoss Messaging, EJB2, and EJB3 are the applications from the Remoting perspective. A Client may be created with a subsystem string which associates it with a particular ServerInvocationHandler on the server side. Note that if a ServerInvoker is configured with only a single ServerInvocationHandler, the use of a subsystem string is optional.

2.3. Callbacks

One more concept is necessary to make sense of the bisocket transport, discussed below in the The bisocket transport chapter. An ordinary invocation leads to a synchronous response from the server, but asynchronous communication is also possible from the server to the client. When a call is make to one of the overloaded variants of the Client method

addListener(InvokerCallbackHandler callbackHandler) throws Throwable;

the passed instance of InvokerCallbackHandler is registered as a listener for asynchronous communication, and, on the server side, the ServerInvocationHandler associated with the Client is given a "proxy" for the InvokerCallbackHandler which it can use to send asynchronous org.jboss.remoting.callback.Callback objects, or, more simply, callbacks.

There are two kinds of callbacks. For push callbacks, a dedicated ServerInvoker is created on the client side and the server side ServerInvocationHandler makes invocations, by way of the "proxy", on that ServerInvoker to send callback objects to the client side. Under the surface, the "proxy" creates a Client to handle those invocations. On the other hand, pull callbacks generated by the ServerInvocationHandler are stored on the server side, and a poller is created on the client side which makes invocations on the server side ServerInvoker to retrieve any stored callbacks.