InvocationBroker

java.lang.Object
- info.pppc.base.system.InvocationBroker

All Implemented Interfaces:

IOperator
```
public final class InvocationBroker
extends java.lang.Object
implements IOperator
```
The invocation broker is responsible for synchronization, threading and performing remote and local calls. The invocation broker currently uses three types of invocations to perform and synchronize on remote invocations. The invoke type to perform a remote call, the result type to retrieve a result and the remove type to remove the result from the table. The invocation broker expects the to occur exactly once (!) for each invocation. Otherwise it will generate error messages and you might end up with some dead entries in the tables of the broker. However, the broker should never crash, even if you pass broken invocations. With respect to application synchronization, the invocation broker supports three different synchronizations: synchronous, asynchronous and deferred synchronous. For synchronous calls the broker will not return before the call has finished. The result of the call will be contained in the result or exception variable of the invocation. For asynchronous calls, the broker will return immediately and there is no way of retrieving any results that might have been delivered already. Thus asynchronous calls have a one-way semantic. Deferred synchronous calls will also return immediately. The result object of the invocation will be a future result. If a caller tries to retrieve the exception or the result value of the future result, the result will synchronize with the broker and the call will return as soon as the initial call has finished. Note that this implementation has dependencies with the plug-in manager and is especially fragile to broken semantic plug-in implementations. If you are implementing a semantic plug-in, you should test your implementation with the toString method. After performing all calls, this should print a string that says 0 incoming and 0 outgoing messages otherwise you will end up with some dead entries in the brokers table and you will eventually run out of memory.

Author:

Marcus Handte

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`EVENT_BROKER_SHUTDOWN` The event constant that denotes that the broker is performing a shutdown.
`static java.lang.String`	`PROPERTY_DEVICE_IDENTIFIER` This property is used to derive the local system id upon startup.
`static java.lang.String`	`PROPERTY_DEVICE_NAME` This is the name of the system property that provides the human readable device name.
`static java.lang.String`	`PROPERTY_DEVICE_TYPE` This is the name of the system property that provides the device type.
`static java.lang.String`	`PROPERTY_THREAD_DEFAULT` This is the name of the system property that describes the default number of threads.
`static java.lang.String`	`PROPERTY_THREAD_MAXIMUM` This is the name of the system property that describes the maximum number of threads.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addBrokerListener(int types, IListener listener)` Adds a listener that listeners to certain types of events from the broker.
`DeviceRegistry`	`getDeviceRegistry()` Returns the device registry of this invocation broker.
`static InvocationBroker`	`getInstance()` Returns the invocation broker of this JVM.
`ObjectRegistry`	`getObjectRegistry()` Returns the local object registry of this invocation broker.
`PluginManager`	`getPluginManager()` Returns the plugin manager of this invocation broker.
`void`	`invoke(Invocation invocation)` Called to perform a synchronous call.
`void`	`performOperation(IOperation operation)` Called by some plug-in or application to execute an operation.
`void`	`performOperation(IOperation operation, IMonitor monitor)` Called by some plug-in or application to execute an operation.
`boolean`	`removeBrokerListener(int types, IListener listener)` Removes a previously registered broker listener from the set of broker listeners for the specified types of events.
`void`	`shutdown()` Performs a shutdown of the broker.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PROPERTY_DEVICE_IDENTIFIER
```
public static final java.lang.String PROPERTY_DEVICE_IDENTIFIER
```
    This property is used to derive the local system id upon startup. If the property is set to a long value, the local system id is set to the corresponding value, otherwise the system id is generated using the random number generator.
    
    See Also:
    Constant Field Values
  - PROPERTY_DEVICE_NAME
```
public static final java.lang.String PROPERTY_DEVICE_NAME
```
    This is the name of the system property that provides the human readable device name. If the name contained in this system property exceeds 10 characters it is simply cut off after 10 chars.
    
    See Also:
    Constant Field Values
  - PROPERTY_DEVICE_TYPE
```
public static final java.lang.String PROPERTY_DEVICE_TYPE
```
    This is the name of the system property that provides the device type. The value specified in this property should be a short value and it should be one of the device type constants defined in the device description.
    
    See Also:
    Constant Field Values
  - PROPERTY_THREAD_MAXIMUM
```
public static final java.lang.String PROPERTY_THREAD_MAXIMUM
```
    This is the name of the system property that describes the maximum number of threads. The value specified by this property must contain a non-negative integer. If no value is specified, unlimited (i.e., 0) is assumed.
    
    See Also:
    Constant Field Values
  - PROPERTY_THREAD_DEFAULT
```
public static final java.lang.String PROPERTY_THREAD_DEFAULT
```
    This is the name of the system property that describes the default number of threads. The value specified by this property must contain a non-negative integer. If no value is specified 0 is assumed.
    
    See Also:
    Constant Field Values
  - EVENT_BROKER_SHUTDOWN
```
public static final int EVENT_BROKER_SHUTDOWN
```
    The event constant that denotes that the broker is performing a shutdown. The source object will be the broker that performs the shutdown and the data object will be null.
    
    See Also:
    Constant Field Values
- Method Detail
  - getInstance
```
public static InvocationBroker getInstance()
```
    Returns the invocation broker of this JVM. This is the preferred way to access the internals of base directly. This is for instance used by proxies to access the broker and to perform remote calls.
    
    Returns:
    The only broker on this machine.
  - getDeviceRegistry
```
public DeviceRegistry getDeviceRegistry()
```
    Returns the device registry of this invocation broker.
    
    Returns:
    The device registry of the broker.
  - getObjectRegistry
```
public ObjectRegistry getObjectRegistry()
```
    Returns the local object registry of this invocation broker.
    
    Returns:
    The object registry of the broker.
  - getPluginManager
```
public PluginManager getPluginManager()
```
    Returns the plugin manager of this invocation broker.
    
    Returns:
    The plugin manager of the broker.
  - invoke
```
public void invoke(Invocation invocation)
```
    Called to perform a synchronous call. After the method returns the object stored in the result of the invocation will be a result.
    
    Parameters:
    invocation - The invocation to perform synchronously.
  - performOperation
```
public void performOperation(IOperation operation)
```
    Called by some plug-in or application to execute an operation. The point in time when the operation is executed is defined by the invocation broker that defines the global synchronization and threading policy. A developer should never create his own threads, instead he should use this method to execute something asynchronously.
    
    Specified by:
    
    performOperation in interface IOperator
    
    Parameters:
    operation - The operation to executed by some free thread.
    
    Throws:
    
    java.lang.NullPointerException - Thrown if the operation is null.
  - performOperation
```
public void performOperation(IOperation operation,
                    IMonitor monitor)
```
    Called by some plug-in or application to execute an operation. The point in time when the operation is executed is defined by the invocation broker that defines the global synchronization and threading policy. A developer should never create his own threads, instead he should use this method to execute something asynchronously. A developer can pass a monitor to the method to interface with the operation and to observe its current status.
    
    Specified by:
    
    performOperation in interface IOperator
    
    Parameters:
    operation - The operation to executed by some free thread.
    monitor - The monitor used to interface with the operation.
    
    Throws:
    
    java.lang.NullPointerException - Thrown if the operation is null. If the monitor is null, the broker will create a default monitor.
  - addBrokerListener
```
public void addBrokerListener(int types,
                     IListener listener)
```
    Adds a listener that listeners to certain types of events from the broker. At the present time the only event that is issued by the broker is the EVENT_BROKER_SHUTDOWN event that signals that the system is shutting down.
    
    Parameters:
    types - The types of events to register for.
    listener - The listener to register.
  - removeBrokerListener
```
public boolean removeBrokerListener(int types,
                           IListener listener)
```
    Removes a previously registered broker listener from the set of broker listeners for the specified types of events.
    
    Parameters:
    types - The types of events to unregister.
    listener - The listener to unregister.
    
    Returns:
    True if the listener has been removed.
  - shutdown
```
public void shutdown()
```
    Performs a shutdown of the broker. This will kill the device registry remover thread and it will release all plug-ins of the plug-in manager.

Class InvocationBroker

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROPERTY_DEVICE_IDENTIFIER

PROPERTY_DEVICE_NAME

PROPERTY_DEVICE_TYPE

PROPERTY_THREAD_MAXIMUM

PROPERTY_THREAD_DEFAULT

EVENT_BROKER_SHUTDOWN

Method Detail

getInstance

getDeviceRegistry

getObjectRegistry

getPluginManager

invoke

performOperation

performOperation

addBrokerListener

removeBrokerListener

shutdown