com.owlfish.forestbus

Class ForestClient

java.lang.Object

com.owlfish.forestbus.ForestClient

public class ForestClient
extends java.lang.Object

The ForestClient provides a multi-thread safe client for interfacing to a Forest Bus cluster of nodes. The client handles establishing the connectivity to the individual nodes and finding the current location of leaders for given topics.

ForestClient connects using CBOR RPC.

Constructor Summary

Constructors

Constructor and Description
ForestClient(java.lang.String clusterID, java.lang.String[] nodes) Creates a ForestClient ready for use.

Method Summary

Modifier and Type	Method and Description
void	close() Closes all connections to the cluster.
GetMessagesResult	getMessages(java.lang.String topic, long index, int quantity, boolean wait) getMessages takes the topic, the index, target quantity and a wait flag (boolean) and returns messages from the cluster.
long	getTopicMaxAvailableIndex(java.lang.String topic) Returns the maximum index available in the given topic.
long[]	sendMessages(java.lang.String topic, byte[][] messages, boolean waitForCommit) sendMessages sends a batch of messages to the Forest Bus cluster.

Methods inherited from class java.lang.Object

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

Constructor Detail

ForestClient

public ForestClient(java.lang.String clusterID,
                    java.lang.String[] nodes)

Creates a ForestClient ready for use. Connections to nodes happens on demand rather than in the constructor.

Parameters:

clusterID - the id the cluster is configured with. If this is incorrect ClusterIDMismatchException exceptions will be thrown.

nodes - the array of nodes to connect to. The strings must be in the format name:port and match those given on the nodes when started up with -cbor.

Method Detail

getMessages

public GetMessagesResult getMessages(java.lang.String topic,
                                     long index,
                                     int quantity,
                                     boolean wait)
                              throws ForestBusException

getMessages takes the topic, the index, target quantity and a wait flag (boolean) and returns messages from the cluster.

GetMessages will usually return more or fewer messages than the quantity requested. This ensures efficient message retrieval from the node as messages are aligned to offset and cache boundaries. If any messages are available at the requested index then at least one message will be returned.

If the index requested is no longer available on this node (i.e. clean-up has removed old data) then zero messages will be returned and the RecieveMessagesResults.nextID will be the index of the first available message.

If the messages returned bring the client up to the end of the available messages, then RecieveMessagesResults.nextID will contain the index of what will become the next message when it has been sent. By setting wait to true and passing in the index returned by nextID, GetMessages will block until at least one new message is available, before returning that message/messages.

GetMessages throws Exceptions if no nodes are available, a network error occurs or the topic could not be found. Even if an exception has been thrown - Client.close() must be called to close down all threads.

Parameters:

topic - the name of the topic to get messages from.

index - the index of the first message to retrieve.

quantity - the target number of messages to retrieve.

wait - whether to wait for messages to become available if there are no messages currently at index.

Returns:

GetMessagesResult contains receievedMessages (an array of byte arrays) and nextID which contains the next available ID.

Throws:

ForestBusException - Throws ForestBusException or a subclass of this if there is an error.

getTopicMaxAvailableIndex

public long getTopicMaxAvailableIndex(java.lang.String topic)
                               throws ForestBusException

Returns the maximum index available in the given topic.

If the cluster has been completely shutdown and restarted (rather than a rolling restart of individual nodes) then the commit index may be zero, in which case the maxAvailableIndex will be zero. Once a message has been sent to the cluster in this topic the commit index will be recalculated and the maximum commit index will return as normal.

Parameters:

topic - the name of the topic.

Returns:

the maximum index number of a message in this topic.

Throws:

ForestBusException - Throws ForestBusException or a subclass of this if there is an error.

sendMessages

public long[] sendMessages(java.lang.String topic,
                           byte[][] messages,
                           boolean waitForCommit)
                    throws ForestBusException

sendMessages sends a batch of messages to the Forest Bus cluster.

Messages are a list of sequences of bytes. Sending many messages (hundreds) at once gives better through-put than sending individual messages.

If waitForCommit is false then SendMessages will return as soon as the message has been saved on the leader node for this topic. If waitForCommit is true then SendMessages will only return once the messages have been replicated to a majority of the nodes in the cluster and are therefore committed.

SendMessages throws Exceptions if no leader node is available, a network error occurs or the topic could not be found. Even if an exception has been thrown - Client.close() must be called to close down all threads.

Parameters:

topic - the name of the topic.

messages - an array of byte arrays containing the messages to be sent.

waitForCommit - flag indicating whether to wait until the messages have been committed to the cluster before returning.

Returns:

an array of IDs for the messages sent.

Throws:

ForestBusException - Throws ForestBusException or a subclass of this if there is an error.

close

public void close()

Closes all connections to the cluster. The Client object may still be used, in which case new connections will be opened as required.