com.interfaceware.iguana.plugin
Class Destination

java.lang.Object
  com.interfaceware.iguana.plugin.Destination

public class Destination
extends java.lang.Object

This class is used to implement an Iguana destination plugin.

Destination plugins connect to, and receive messages from Iguana To-Plugin channel components.

Messages are sent from Iguana to the Destination plugin through the messageReceived event. The plugin must set properties on the DestinationMessageReceivedEventOutputs object that will be passed to event handler. This will indicate to Iguana whether message processing was successful.

See:

http://www.interfaceware.com/manual/plugin_receiving.html

for more information.

Constructor Summary

Destination()

Destination(long Handle)

Method Summary

void	addListener(DestinationListener Listener) Adds the specified listener so that it receives events from this Destination object.
void	connect(java.lang.String HostName, int PortNumber, java.lang.String ChannelName) Connects to an Iguana To-Plugin channel component as a destination plugin.
void	disconnect() Disconnects the plugin from Iguana.
void	enableDebugLogging(java.lang.String FileName) Enables logging of internal runtime debug information to the specified file.
protected void	finalize()
int	getConnectTimeout() Time in milliseconds the plugin will wait to handshake with Iguana while executing the connect operation (default 5000 milliseconds).
DisconnectReason	getDisconnectReason() Describes the reason for the plugin's (most recent) disconnection from Iguana.
void	release()
void	removeListener(DestinationListener Listener) Removes the specified listener so that it no longer receives events from this Destination object.
void	setConnectTimeout(int Value) Set method for ConnectTimeout.
void	waitForDisconnect() Waits until the plugin is disconnected from Iguana.
boolean	waitForDisconnectWithTimeout(int TimeoutInMilliseconds) Waits until either the plugin is disconnected from Iguana, or a specified timeout elapses.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Destination

public Destination()
            throws PluginException

Throws:

PluginException

Destination

public Destination(long Handle)
            throws PluginException

Throws:

PluginException

Method Detail

release

public void release()
             throws PluginException

Throws:

PluginException

finalize

protected void finalize()
                 throws PluginException

Overrides:

finalize in class java.lang.Object

Throws:

PluginException

getDisconnectReason

public DisconnectReason getDisconnectReason()
                                     throws PluginException

Describes the reason for the plugin's (most recent) disconnection from Iguana.

Only valid after the plugin has been disconnected, and before any subsequent connection attempts. Specifically, only valid within the disconnected handler or after the return of a call to waitForDisconnect or waitForDisconnectWithTimeout, and before any subsequent calls to connect.

Throws:

PluginException

getConnectTimeout

public int getConnectTimeout()
                      throws PluginException

Time in milliseconds the plugin will wait to handshake with Iguana while executing the connect operation (default 5000 milliseconds).

For a heavily loaded Iguana server running on a slow machine this may need a higher value than the default value.

See also the setConnectTimeout method.

Throws:

PluginException

setConnectTimeout

public void setConnectTimeout(int Value)
                       throws PluginException

Set method for ConnectTimeout.

See ConnectTimeout.

Parameters:

Value - Value to set ConnectTimeout to.

Throws:

PluginException

enableDebugLogging

public void enableDebugLogging(java.lang.String FileName)
                        throws PluginException

Enables logging of internal runtime debug information to the specified file.

Must be called before any other methods, and may only be called once per Destination instance.

This function should only be used at the request of iNTERFACEWARE Technical Support.

Parameters:

FileName - Name of the file where debug information is to be logged.

Throws:

PluginException

connect

public void connect(java.lang.String HostName,
                    int PortNumber,
                    java.lang.String ChannelName)
             throws PluginException

Connects to an Iguana To-Plugin channel component as a destination plugin.

Normally, this method is called as the plugin starts and is ready to receive data from Iguana or if Iguana has disconnected from the plugin (for example, after returning from a call to waitForDisconnect).

It may not be called from within an event handler (for example, may not be called from within the disconnected handler).

If a connection is not established within the timeout period specified by ConnectTimeout, an exception will be thrown. The default timeout period of 5000 milliseconds should suffice for most plugins, and should only be adjusted if connection timeouts are observed.

One common point of confusion with users is the choice of port number for this call. This must be the port number for the Plugin Communication Server, which is typically 6123, not the LLP port for the particular plugin channel.

Throws: Function throws an exception upon connection failure or timeout, or if called from within an event handler.

Parameters:

HostName - Iguana machine hostname or IP address (typically 'localhost' if the plugin and Iguana are running on the same machine).

PortNumber - Iguana Plugin Communication Server port number (typically 6123).

ChannelName - Iguana channel name.

Throws:

PluginException

disconnect

public void disconnect()
                throws PluginException

Disconnects the plugin from Iguana.

Results in DisconnectReason being set to DueToPlugin.

Throws:

PluginException

waitForDisconnect

public void waitForDisconnect()
                       throws PluginException

Waits until the plugin is disconnected from Iguana.

May not be called from within an event handler (for example, may not be called from within the disconnected handler).

Throws:

PluginException

waitForDisconnectWithTimeout

public boolean waitForDisconnectWithTimeout(int TimeoutInMilliseconds)
                                     throws PluginException

Waits until either the plugin is disconnected from Iguana, or a specified timeout elapses.

May not be called from within an event handler (for example, may not be called from within the disconnected handler).

Parameters:

TimeoutInMilliseconds - Timeout (in milliseconds) to wait for disconnection.

Returns:

Returns true if the plugin disconnected from Iguana, or false if the timeout elapsed before the plugin was disconnected from Iguana.

Throws:

PluginException

addListener

public void addListener(DestinationListener Listener)
                 throws PluginException

Adds the specified listener so that it receives events from this Destination object.

Throws:

PluginException

See Also:

removeListener

removeListener

public void removeListener(DestinationListener Listener)
                    throws PluginException

Removes the specified listener so that it no longer receives events from this Destination object.

Throws:

PluginException

See Also:

addListener