MessageStream (AMPS Java Client (5.3.4.0.14fbce6f.256885))

java.lang.Object
- com.crankuptheamps.client.MessageStream

All Implemented Interfaces:

ConnectionStateListener, MessageHandler, java.lang.AutoCloseable, java.lang.Iterable<Message>, java.util.Iterator<Message>
```
public class MessageStream
extends java.lang.Object
implements java.util.Iterator<Message>, java.lang.Iterable<Message>, MessageHandler, ConnectionStateListener, java.lang.AutoCloseable
```
MessageStream provides an iteration abstraction over the results of an AMPS command such as a subscribe, a SOW query, or SOW delete. MessageStream is produced when calling Client.execute() and continues iterating over the results until the connection is closed, or the iterator is explicitly closed, or when the SOW query is ended. You can use a MessageStream as you would other Iterators, for example, using a for loop (Java 1.7):
```
 MessageStream stream = Client.execute(new Command("sow").setTopic("/orders")).timeout(1000);
 for(Message message : stream)
 {
   ...
 }
 
```

Field Summary

Fields
Modifier and Type	Field and Description
`protected Client`	`_client`
`protected CommandId`	`_commandId`
`protected Message`	`_current`
`protected int`	`_maxDepth`
`protected Field`	`_previousBookmark`
`protected Field`	`_previousTopic`
`protected java.util.concurrent.ConcurrentLinkedQueue<Message>`	`_q`
`protected CommandId`	`_queryId`
`protected int`	`_requestedAcks`
`protected java.util.concurrent.locks.Lock`	`_sowKeyLock`
`protected java.util.HashMap<java.lang.String,Message>`	`_sowKeyMap`
`protected int`	`_state`
`protected CommandId`	`_subId`
`protected boolean`	`_timedOut`
`protected int`	`_timeout`

Fields inherited from interface com.crankuptheamps.client.ConnectionStateListener
Connected, Disconnected, HeartbeatInitiated, LoggedOn, PublishReplayed, Resubscribed, Shutdown, UNKNOWN

Constructor Summary

Constructors
Modifier Constructor and Description

protected MessageStream(Client client_)
Constructs an instance of message stream with the given client.

Constructors
Modifier	Constructor and Description
`protected`	`MessageStream(Client client_)` Constructs an instance of message stream with the given client.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Closes this MessageStream, unsubscribing from AMPS if applicable.
`MessageStream`	`conflate()` Causes messages to be conflated by SOW key.
`void`	`connectionStateChanged(int newState_)` Used to indicate if there was a change in state with connection.
`int`	`getDepth()` Gets the number of messages currently buffered by this message stream.
`static MessageStream`	`getEmptyMessageStream()` Method to retrieve the empty MessageStream.
`int`	`getMaxDepth()` Gets the allowed maximum depth of the internal message buffer before this stream will push-back on reads from the server.
`int`	`getTimeout()` Gets the currently set timeout value for self (zero if none).
`boolean`	`hasNext()` Implements `Iterator.hasNext()` for a message stream.
`void`	`invoke(Message message)` Method for the AMPS client to call when a message is received.
`boolean`	`isConflating()` Indicates whether this message stream is conflating messages by SOW key.
`boolean`	`isConnected()` Returns true if the connection to AMPS is still active, or false if a disconnect is detected.
`java.util.Iterator<Message>`	`iterator()` Implements `Iterable.iterator()` to return this instance.
`MessageStream`	`maxDepth(int maxDepth_)` Sets the maximum number of messages that will be buffered in memory by this stream before taking measures to slow reads.
`Message`	`next()` Implements `Iterator.next()` for a message stream.
`void`	`remove()` Operation not supported.
`protected void`	`setAcksOnly(CommandId commandId_, int ackTypes_)` Changes the current state of the message stream to `STATE_AcksOnly`.
`protected void`	`setCommandId(CommandId commandId_)` When this message stream is the result of a form of subscribe command, this gets called with the command ID of the command.
`protected void`	`setQueryId(CommandId queryId_)` When this message stream is the result of a form of SOW command, this gets called with the query ID of the command.
`protected void`	`setRunning()` Changes the current state of the message stream to `STATE_Reading`.
`protected void`	`setSOWOnly()` Changes the current state of the message stream to `STATE_SOWOnly`.
`protected void`	`setStatsOnly()` Changes the current state of the message stream to `STATE_StatsOnly`.
`protected void`	`setSubscription(CommandId subId_)` When this message stream is the result of a subscription command, this gets called with the subscription ID.
`MessageStream`	`timeout(int timeout_)` Sets a timeout on self.

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

Methods inherited from interface java.util.Iterator
forEachRemaining

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - _commandId
```
protected CommandId _commandId
```
  - _queryId
```
protected CommandId _queryId
```
  - _subId
```
protected CommandId _subId
```
  - _client
```
protected Client _client
```
  - _q
```
protected java.util.concurrent.ConcurrentLinkedQueue<Message> _q
```
  - _sowKeyMap
```
protected java.util.HashMap<java.lang.String,Message> _sowKeyMap
```
  - _sowKeyLock
```
protected java.util.concurrent.locks.Lock _sowKeyLock
```
  - _current
```
protected Message _current
```
  - _state
```
protected volatile int _state
```
  - _timeout
```
protected int _timeout
```
  - _timedOut
```
protected boolean _timedOut
```
  - _maxDepth
```
protected volatile int _maxDepth
```
  - _requestedAcks
```
protected int _requestedAcks
```
  - _previousTopic
```
protected Field _previousTopic
```
  - _previousBookmark
```
protected Field _previousBookmark
```
- Constructor Detail
  - MessageStream
```
protected MessageStream(Client client_)
```
    Constructs an instance of message stream with the given client. The message stream will hold a reference to the provided client, and registers itself as a connection state listener for the client.
    
    Parameters:
    
    client_ - the client to use for this message stream
- Method Detail
  - getEmptyMessageStream
```
public static MessageStream getEmptyMessageStream()
```
    Method to retrieve the empty MessageStream.
    
    Returns:
    
    the static, empty MessageStream
  - setSubscription
```
protected void setSubscription(CommandId subId_)
```
    When this message stream is the result of a subscription command, this gets called with the subscription ID.
    
    Parameters:
    
    subId_ - the CommandId to set as the SubscriptionId of this command
  - setQueryId
```
protected void setQueryId(CommandId queryId_)
```
    When this message stream is the result of a form of SOW command, this gets called with the query ID of the command.
    
    Parameters:
    
    queryId_ - the CommandId to set as the QueryId of this command
  - setCommandId
```
protected void setCommandId(CommandId commandId_)
```
    When this message stream is the result of a form of subscribe command, this gets called with the command ID of the command.
    
    Parameters:
    
    commandId_ - the CommandId to set as the QueryId of this command
  - setSOWOnly
```
protected void setSOWOnly()
```
    Changes the current state of the message stream to STATE_SOWOnly.
  - setStatsOnly
```
protected void setStatsOnly()
```
    Changes the current state of the message stream to STATE_StatsOnly.
  - setAcksOnly
```
protected void setAcksOnly(CommandId commandId_,
                           int ackTypes_)
```
    Changes the current state of the message stream to STATE_AcksOnly.
    
    Parameters:
    
    commandId_ - The commandId of the command for the acks.
    
    ackTypes_ - The types of acks that will be returned.
  - setRunning
```
protected void setRunning()
```
    Changes the current state of the message stream to STATE_Reading.
  - timeout
```
public MessageStream timeout(int timeout_)
```
    Sets a timeout on self. If no message is received in this timeout, next() returns 'null', but leaves the stream open.
    
    Parameters:
    
    timeout_ - The timeout in milliseconds, or 0 for infinite timeout.
    
    Returns:
    
    Returns self, so it can be used in a "builder" style.
  - getTimeout
```
public int getTimeout()
```
    Gets the currently set timeout value for self (zero if none).
    
    Returns:
    
    the timeout set on this command
    
    See Also:
    
    timeout(int)
  - conflate
```
public MessageStream conflate()
```
    Causes messages to be conflated by SOW key. You call this method on your MessageStream to use client-side conflation and continue to use the MessageStream as usual to process the messages you're interested in. Client-side conflation works when you have messages with unique identifiers(SowKeys). When using it with delta subscriptions (where you receive only the changes between messages), be aware that client-side conflation replaces the whole message, potentially causing updates to be lost if messages are replaced. In such cases, server-side conflation(handled by AMPS on the server) might be a safer option, as it can merge deltas more effectively.
    
    Returns:
    
    Returns this instance so that various operations can be chained together.
  - isConflating
```
public boolean isConflating()
```
    Indicates whether this message stream is conflating messages by SOW key.
    
    Returns:
    
    true if this message stream is conflating messages
    
    See Also:
    
    conflate()
  - maxDepth
```
public MessageStream maxDepth(int maxDepth_)
```
    Sets the maximum number of messages that will be buffered in memory by this stream before taking measures to slow reads. When this threshold is exceeded the message stream must push back on the client's background reader thread, delaying reads from the client's socket connection until the buffer depth reaches or falls below the maxDepth. Due to this behavior, there are several caveats that must be observed when using a max depth on a message stream:
    - You should not create and use more than one MessageStream instance at the same time from a given Client instance. It's also recommended not to use this and an asynchronous MessageHandler on the same client instance, since your asynchronous message handler could be starved.
    - Inside your message processing loop that iterates the MessageStream, you should not publish or execute AMPS commands using the same Client instance that created the MessageStream you are processing.
    Ignoring these caveats can potentially cause your AMPS client to hang because the background thread may never be able to read important internal acknowledgement control messages.
    
    If these caveats are unsuitable for your use case, alternative solutions include (1) using the pause/resume or rate options for a bookmark subscription; (2) using the top_n/skip_n options to page a large SOW query; (3) using message stream conflation with a SOW via conflate(); (4) use your own asynchronous MessageHandler implementation instead of using this synchronous message stream, so that you can process one message at a time without needing to store it; or (5) creating an additional client instance so that its background reader thread isn't affected by max depth push-back by this message stream.
    Parameters:
    
    maxDepth_ - The maximum depth to set on the stream's internal buffer. The default value comes from Client.setDefaultMaxDepth(int), which defaults to Integer.MAX_VALUE.
    
    Returns:
    
    This message stream instance.
  - getMaxDepth
```
public int getMaxDepth()
```
    Gets the allowed maximum depth of the internal message buffer before this stream will push-back on reads from the server.
    
    Returns:
    
    the current maximum depth
    
    See Also:
    
    maxDepth(int)
  - getDepth
```
public int getDepth()
```
    Gets the number of messages currently buffered by this message stream. This typically would be no more than maxDepth + 1, unless the maxDepth was lowered after messages were buffered. NOTE: If iterating this stream use hasNext() instead.
    
    Returns:
    
    the current depth of the message stream
    
    See Also:
    
    hasNext()
  - connectionStateChanged
```
public void connectionStateChanged(int newState_)
```
    Used to indicate if there was a change in state with connection.
    
    Specified by:
    
    connectionStateChanged in interface ConnectionStateListener
    
    Parameters:
    
    newState_ - integer to compare to Disconnected
  - hasNext
```
public boolean hasNext()
```
    Implements Iterator.hasNext() for a message stream. //might need a comment
    
    Specified by:
    
    hasNext in interface java.util.Iterator<Message>
  - next
```
public Message next()
```
    Implements Iterator.next() for a message stream.
    
    Specified by:
    
    next in interface java.util.Iterator<Message>
  - invoke
```
public void invoke(Message message)
```
    Description copied from interface: MessageHandler
    
    Method for the AMPS client to call when a message is received.
    The AMPS client reuses the same message object in successive calls to the message handler, resetting the contents of the object for each call. Should you need to use the data in the message outside of the call to the message handler, you must copy the message object or copy data out of the message object.
    
    Specified by:
    
    invoke in interface MessageHandler
    
    Parameters:
    
    message - the message received from AMPS. As mentioned above, this message object is reused by successive calls to the handler.
  - remove
```
public void remove()
```
    Operation not supported. Implements Iterator.remove() to throw UnsupportedOperationException.
    
    Specified by:
    
    remove in interface java.util.Iterator<Message>
  - iterator
```
public java.util.Iterator<Message> iterator()
```
    Implements Iterable.iterator() to return this instance.
    
    Specified by:
    
    iterator in interface java.lang.Iterable<Message>
  - isConnected
```
public boolean isConnected()
```
    Returns true if the connection to AMPS is still active, or false if a disconnect is detected.
    
    Returns:
    
    true if the connection is active, false if the Client has disconnected since the message stream was created
  - close
```
public void close()
```
    Closes this MessageStream, unsubscribing from AMPS if applicable.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable

Class MessageStream

Field Summary

Fields inherited from interface com.crankuptheamps.client.ConnectionStateListener

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Methods inherited from interface java.lang.Iterable

Field Detail

_commandId

_queryId

_subId

_client

_q

_sowKeyMap

_sowKeyLock

_current

_state

_timeout

_timedOut

_maxDepth

_requestedAcks

_previousTopic

_previousBookmark

Constructor Detail

MessageStream

Method Detail

getEmptyMessageStream

setSubscription

setQueryId

setCommandId

setSOWOnly

setStatsOnly

setAcksOnly

setRunning

timeout

getTimeout

conflate

isConflating

maxDepth

getMaxDepth

getDepth

connectionStateChanged

hasNext

next

invoke

remove

iterator

isConnected

close