EClient (eBus Core 5.2.1 API)

java.lang.Object
- java.lang.ref.Reference<T>
- - java.lang.ref.WeakReference<EObject>
  - - net.sf.eBus.client.EClient

All Implemented Interfaces:

Comparable<EClient>
```
public final class EClient
extends WeakReference<EObject>
implements Comparable<EClient>
```
EClient ties together eBus message routing and message processing. eBus views an application instance in three ways: 1) an implementation of one or more eBus interfaces (publisher, subscriber, requester, or replier), 2) the owner of open feeds and 3) the target of callback tasks. EClient stores the instance's open feeds and un-executed callback tasks.
eBus has a client-oriented execution mode rather than task-oriented. When the client's task list is not empty, the EClient instance is placed on a run queue where it appears only once. RQThread threads remove clients from this run queue and execute the client's tasks. The Dispatcher continues executing the client's tasks until the client task queue or run quantum is exhausted. When the nanosecond run quantum reaches zero, the client is appended to the run queue if it has pending tasks. The run quantum reset to the configurable initial quantum value when a dispatcher thread acquires the client. Note: when the run quantum expires, eBus cannot preempt the client. It is possible for the client to run indefinitely, taking over the Dispatcher thread.

EClient maintains a weak reference to the application instance. When eBus detects that the application instance is finalized, all feeds left open by the instance are closed. If the application instance is a replier, then all active requests will receive an error reply. The client's un-executed tasks are cleared.

eBus Client Execution
EClient maintains one or more RQThread groups where each group has a separate run queue. Each client is assigned to an executor group based on the encapsulated application class. If the application class is not assigned to a particular executor group, then the class is assigned to the default executor group. The executor groups are defined via configuration. If no executors are defined, then there is one Dispatcher thread for each core using a single, blocking run queue. Executors block until there is an runnable EClient posted to group run queue. As stated previously, an EClient is assigned to only one client dispatcher thread at a time. This makes an EClient instance effectively single-threaded if that client is accessed only by dispatcher threads. While a client may be accessed by different dispatcher threads over time, it will be accessed by only one at any given moment in time.
Each EClient is assigned a integer identifier which is guaranteed unique for the client lifespan. When the client is disposed, the client identifier is re-used and may be assigned to a new, future eBus client instance. An EClient is disposed when the encapsulated application instance is finalized.

The reason for EClient is because eBus requires application objects to implement interfaces in order to interface with eBus, not extend an eBus abstract class. This class provides the functionality that an abstract client class would provide.

Author:

Charles Rapp

See Also:

EFeed, ESubject

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class EClient.ClientLocation
An eBus client is either local to this JVM or in a remote JVM.

Nested Classes
Modifier and Type	Class and Description
`static class`	`EClient.ClientLocation` An eBus client is either local to this JVM or in a remote JVM.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`clientId()` Returns the unique eBus client identifier.
`int`	`compareTo(EClient client)` Returns an integer value <, equal to, or > zero based on whether `this EClient` instance's identifier is <, equal to, or > `client`'s identifier.
`static void`	`dispatch(Runnable task, EObject client)` Posts `task` to `client`'s task queue (this is the same task queue used for eBus message delivery).
`boolean`	`equals(Object o)` Returns `true` if `o` is a non-`null EClient` instance with the same client identifier as `this` instance; otherwise, returns `false`.
`static EClient`	`findOrCreateClient(EObject client, EClient.ClientLocation location)` Returns the eBus proxy for the given eBus client instance.
`int`	`hashCode()` Returns the unique client identifier as the hash code.
`EClient.ClientLocation`	`location()` Returns the client location.
`EObject`	`target()` Returns the target client.
`String`	`toString()`

Methods inherited from class java.lang.ref.Reference
clear, enqueue, get, isEnqueued

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - compareTo
```
public int compareTo(EClient client)
```
    Returns an integer value <, equal to, or > zero based on whether this EClient instance's identifier is <, equal to, or > client's identifier.
    
    Specified by:
    
    compareTo in interface Comparable<EClient>
    
    Parameters:
    
    client - comparison object.
    
    Returns:
    
    integer value <, equal to, or > zero.
  - equals
```
public boolean equals(Object o)
```
    Returns true if o is a non-null EClient instance with the same client identifier as this instance; otherwise, returns false.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    o - comparison object.
    
    Returns:
    
    true if the client identifiers are equal.
  - hashCode
```
public int hashCode()
```
    Returns the unique client identifier as the hash code.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    client identifier.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - target
```
public EObject target()
```
    Returns the target client. May return null if the target client is finalized.
    
    Returns:
    
    eBus client.
  - clientId
```
public int clientId()
```
    Returns the unique eBus client identifier. This identifier is guaranteed unique for the client lifespan only.
    
    Returns:
    
    eBus client identifier.
  - location
```
public EClient.ClientLocation location()
```
    Returns the client location.
    
    Returns:
    
    client location.
  - findOrCreateClient
```
public static EClient findOrCreateClient(EObject client,
                                         EClient.ClientLocation location)
```
    Returns the eBus proxy for the given eBus client instance. If the proxy does not yet exist, then creates the proxy and places the proxy into the map. There is only one proxy created for each client independent of the number of eBus interfaces the client implements.
    
    Parameters:
    
    client - the eBus client.
    
    location - EClient.ClientLocation.LOCAL if the client is local to this JVM and EClient.ClientLocation.REMOTE if it exists in a remote eBus application.
    
    Returns:
    
    the eBus client proxy.
  - dispatch
```
public static void dispatch(Runnable task,
                            EObject client)
```
    Posts task to client's task queue (this is the same task queue used for eBus message delivery). If the task queue was originally empty, then the client posted to its run queue for execution by a RQThread.
    If client is unknown to eBus, then a new EClient instance will be created with a weak reference to client. client does not need to be an eBus publisher/ subscriber/requestor/replier.
    
    Parameters:
    
    task - post to the client task queue.
    
    client - task is for this client.
    
    Throws:
    
    NullPointerException - if either task or client is null.

Class EClient

eBus Client Execution

Nested Class Summary

Method Summary

Methods inherited from class java.lang.ref.Reference

Methods inherited from class java.lang.Object

Method Detail

compareTo

equals

hashCode

toString

target

clientId

location

findOrCreateClient

dispatch