com.interfaceware.iguana.plugin
Class Source

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

public class Source
extends java.lang.Object

This class is used to implement an Iguana source plugin.

Source plugins connect to, and send messages to Iguana From-Plugin channel components.

Messages are sent to Iguana using a "polling" or "pull" approach (as opposed to a "push" approach). Iguana sends a message request to the Source plugin, raising the messageRequested event. The Source plugin responds with the next available unacknowledged message. Once Iguana has received and enqueued the message, a message request completed notification is sent back to the Source plugin, raising the messageRequestCompleted event. The Source plugin notes that the message has been acknowledged, and that it can advance to the next available message.

The message polling cycle repeats without delay while messages are available. Once all available messages have been transferred (indicated by the plugin responding to a message request with an empty message), the cycle repeats at an interval determined by the Polling Time configured in the channel's From-Plugin component.

See

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

for more information.

Constructor Summary

Source()

Source(long Handle)

Method Summary

void	addListener(SourceListener Listener) Adds the specified listener so that it receives events from this Source object.
void	connect(java.lang.String HostName, int PortNumber, java.lang.String ChannelName) Connects to an Iguana From-Plugin channel component as a source 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(SourceListener Listener) Removes the specified listener so that it no longer receives events from this Source 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

Source

public Source()
       throws PluginException

Throws:

PluginException

Source

public Source(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 Source 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 From-Plugin channel component as a source plugin.

Should be called only while the plugin is disconnected (for example, after a return from waitForDisconnect).

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.

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. Returns false if the timeout elapsed before the plugin was disconnected from Iguana.

Throws:

PluginException

addListener

public void addListener(SourceListener Listener)
                 throws PluginException

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

Throws:

PluginException

See Also:

removeListener

removeListener

public void removeListener(SourceListener Listener)
                    throws PluginException

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

Throws:

PluginException

See Also:

addListener