com.sonicsw.stream
Interface SonicInputStreamController

public interface SonicInputStreamController

A SonicInputSteamController object is used to create instances of SonicStream objects, and to receive data via those stream instances. The stream controller object is also used to send notification messages from consumers of SonicStream objects back to the sender.

Method Summary

Message	buildSenderNotification(int type, SonicStreamException ex) Builds a notification message to send to the SonicStream sender.
Message	buildSenderNotification(int type, SonicStream ss, SonicStreamException ex) Builds a notification message to send to the sender.
void	close() Closes all streams managed by the SonicInputStreamController instance and closes the JMS objects created by the controller instance.
SonicStream	getNextFullStream(long timeToWait) Returns the next available full stream to be read.
SonicStream	getNextStream(long timeToWait) Returns the next available stream to be read.
Destination	getNotificationDestination() Returns the default notification JMS destination of the SonicInputStreamController instance.
Destination	getStreamDestination() Returns JMS destination from which stream contents are read.
boolean	isFullStreamAvailable() Indicates if entire content of a SonicStream is available to be read.
boolean	isPartStreamAvailable() Indicates if at least a portion of a SonicStream is available to be read.
void	registerExceptionListener(SonicStreamExceptionListener listener) Registers a listener that will receive notification of asynchronous errors.
void	releaseStream(SonicStream ss) Closes the specified SonicStream instance and releases its associated resources.
void	sendNotification(Message msg) Sends a notification to the sender.
void	sendNotification(SonicStream ss, Message msg) Sends a notification to the sender.

Method Detail

registerExceptionListener

void registerExceptionListener(SonicStreamExceptionListener listener)

Registers a listener that will receive notification of asynchronous errors.

Only a single listener may be registered at a given time.

If this method is invoked multiple times, with a different SonicStreamExceptionListener reference each time, only the listener specified in the last invocation of this method will receive notifications.

Parameters:

listener - reference to a SonicStreamExceptionListener instance

getNextStream

SonicStream getNextStream(long timeToWait)
                          throws SonicStreamException

Returns the next available stream to be read.

Parameters:

timeToWait - indicates the amount of time (in seconds) the caller is prepared to wait for the first message of the stream to arrive; a value of zero (0) is treated as an infinite timeout.

Returns:

reference to a SonicStream instance, or null if no stream is available within the specified timeout period

Throws:

SonicStreamException

getNextFullStream

SonicStream getNextFullStream(long timeToWait)
                              throws SonicStreamException

Returns the next available full stream to be read.

Note that use of this method will likely result in the use of more heap memory than the getNextStream method, as the entire content of the SonicStream is assembled in memory before the SonicStream may be read.

An exception will be thrown if the getNextFullStream method is invoked and the streams runtime detects that there is not enough space to hold the stream. Applications should ensure that enough space will be available by increasing the readahead window size via the setReadaheadWindowSize method of SonicStreamFactory prior to creating a SonicInputController instance.

Parameters:

timeToWait - indicates the amount of time (in seconds) the caller is prepared to wait for the full stream to become available; a value of zero (0) is treated as an infinite timeout.

Returns:

reference to a full SonicStream instance; null if no stream is available within the specified timeout period

Throws:

SonicStreamException

sendNotification

void sendNotification(SonicStream ss,
                      Message msg)
                      throws SonicStreamException

Sends a notification to the sender.

The message must have been created using one of the buildSenderNotification methods.

Parameters:

ss - reference to SonicStream instance whose otification destination will be used as the destination for the notification; if null, the notification is sent to the default notification destination defined in the SonicStreamFactory

msg - reference to a JMS TextMessge instance obtained via an invocation of "buildSenderNotification"

Throws:

SonicStreamException

See Also:

sendNotification(Message)

sendNotification

void sendNotification(Message msg)
                      throws SonicStreamException

Sends a notification to the sender.

The message must have been created using one of the buildSenderNotification methods.

The message is sent to the default notification destination defined in the SonicStreamFactory.

Parameters:

msg - reference to a JMS TextMessge instance obtained via an invocation of "buildSenderNotification"

Throws:

SonicStreamException

See Also:

sendNotification(SonicStream, Message)

buildSenderNotification

Message buildSenderNotification(int type,
                                SonicStream ss,
                                SonicStreamException ex)
                                throws SonicStreamException

Builds a notification message to send to the sender.

The notification message is a JMS TextMessage (and the application can create/set the body content).

The properties set for the message will be dependent upon the notification type.

The predefined notification types are specified in SonicStreamConstants, and include NOTIFY_REC_STARTED, NOTIFY_REC_COMPLETED, NOTIFY_REC_ERROR, and NOTIFY_REC_RETRY_REQ.

Application-defined types may also be specified, so long as the type ID used for the application-defined type is larger than the values used as type ID for the predefined Sonic types (in SonicStreamConstants).

Based on notification type, this method will set the following properties (defined in SonicStreamConstants):

For all notification types:

• STR_NOTIFY_TYPE
• STR_RECEIVER_NAME
• STR_ID (obtained from the input SonicStream instance)

For the NOTIFY_REC_ERROR notification type:

• STR_RECEIVER_ERRORCODE
• STR_RECEIVER_ERRORMSG
• error info is obtained from the stream status or from the supplied exception.

For the NOTIFY_REC_RETRY_REQ notification type:

• STR_RECEIVER_ERRORCODE (if ss or exc is available)
• STR_RECEIVER_ERRORMSG (if available)
• the current stream topic is set as the 'replyTo' destination

Parameters:

type - One of the types in SonicStreamConstants:

• NOTIFY_REC_STARTED
• NOTIFY_REC_COMPLETED
• NOTIFY_REC_ERROR
• NOTIFY_REC_RETRY_REQ
• or an application-defined type, with typeid > Sonic types

ss - reference to a SonicStream instance

ex - reference to a SonicStreamException instance; if non-null, errorCode will be obtained from the exception

Returns:

JMS TextMessage with the approprite properties set; the application can add additional properties

Throws:

SonicStreamException

See Also:

buildSenderNotification(int, SonicStreamException)

buildSenderNotification

Message buildSenderNotification(int type,
                                SonicStreamException ex)
                                throws SonicStreamException

Builds a notification message to send to the SonicStream sender.

The notification message is a JMS TextMessage (and the application can create/set the body content). The properties set for the message will be dependent upon the notification type.

Parameters:

type - notification type; either one of the pre-defined notification types in SonicStreamConstants, or an application-defined type (with a type ID value greater than those specified for the pre-defined notification types in SonicStreamConstants)

ex - reference to a SonicStreamException instance; if non-null, errorCode will be obtained from the exception

Returns:

JMS TextMessage with the approprite properties set; the application can add additional properties

Throws:

SonicStreamException

See Also:

buildSenderNotification(int, SonicStream, SonicStreamException)

releaseStream

void releaseStream(SonicStream ss)
                   throws SonicStreamException

Closes the specified SonicStream instance and releases its associated resources.

Parameters:

ss - reference to the SonicStream instance to be closed

Throws:

SonicStreamException

isFullStreamAvailable

boolean isFullStreamAvailable()
                              throws SonicStreamException

Indicates if entire content of a SonicStream is available to be read.

Returns:

true if all the data of a SonicStream instance is available to be read

Throws:

SonicStreamException

isPartStreamAvailable

boolean isPartStreamAvailable()
                              throws SonicStreamException

Indicates if at least a portion of a SonicStream is available to be read.

Returns:

true if at least one segment of a SonicStream instance is available to be read

Throws:

SonicStreamException

close

void close()
           throws SonicStreamException

Closes all streams managed by the SonicInputStreamController instance and closes the JMS objects created by the controller instance.

Throws:

SonicStreamException

getStreamDestination

Destination getStreamDestination()

Returns JMS destination from which stream contents are read.

Returns:

javax.jms.Destination

getNotificationDestination

Destination getNotificationDestination()

Returns the default notification JMS destination of the SonicInputStreamController instance.

Returns:

javax.jms.Destination