Class MessageBus
- All Implemented Interfaces:
ConfigHandler
,MessageHandler
,NetworkOwner
,ReplyHandler
A message bus contains the factory for creating sessions to send, receive and forward messages.
There are three types of sessions:
Source sessions
sends messages and receives repliesIntermediate sessions
receives messages on their way to their final destination, and may decide to forward the messages or reply directly.Destination sessions
are the final recipient of messages, and are expected to reply to every one of them, but may not forward messages.
A message bus is configured with a protocol
. This table
enumerates the permissible routes from intermediates to destinations and the
messaging semantics of each hop.
- Assign a route to every send message from its routing table
- Deliver every message it accepts to the next hop on its route or deliver a failure reply.
- Deliver replies back to message sources through all the intermediate hops.
- Create a message bus implementation and set properties on this implementation once.
- Create sessions using that message bus many places.
- Author:
- bratseth, Simon Thoresen Hult
-
Nested Class Summary
-
Constructor Summary
ConstructorDescriptionMessageBus
(NetworkMultiplexer net, MessageBusParams params) Constructs an instance of message bus.MessageBus
(Network net, MessageBusParams params) Constructs an instance of message bus.MessageBus
(Network net, List<Protocol> protocols) Convenience constructor that proxiesMessageBus(Network, MessageBusParams)
by adding the given protocols to a defaultMessageBusParams
object. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Connects the given session to the network, so it will receive requests.Creates a destination session on top of this message bus using the given handlers and parameter object.createDestinationSession
(String name, boolean broadcastName, MessageHandler handler) This is a convenience method to callcreateDestinationSession(DestinationSessionParams)
with default values for theDestinationSessionParams
object.Creates an intermediate session on top of this message bus using the given handlers and parameter object.createIntermediateSession
(String name, boolean broadcastName, MessageHandler msgHandler, ReplyHandler replyHandler) This is a convenience method to callcreateIntermediateSession(IntermediateSessionParams)
with default values for theIntermediateSessionParams
object.createSourceSession
(ReplyHandler handler) This is a convenience method to callcreateSourceSession(SourceSessionParams)
with default values for theSourceSessionParams
object.createSourceSession
(ReplyHandler handler, SourceSessionParams params) This is a convenience method to callcreateSourceSession(SourceSessionParams)
by first assigning the reply handler to the parameter object.Creates a source session on top of this message bus.void
deliverMessage
(Message msg, String session) All messages that arrive in the network layer is passed to its owner through this function.void
deliverReply
(Reply reply, ReplyHandler handler) boolean
destroy()
Sets the destroyed flag to true.Returns the connection spec string for the network layer of this message bus.int
Deprecated, for removal: This API element is subject to removal in a future version.int
Deprecated, for removal: This API element is subject to removal in a future version.int
Deprecated.int
Deprecated.getProtocol
(com.yahoo.text.Utf8Array name) All messages are sent across the network with its accompanying protocol name so that it can be decoded at the receiving end.Deprecated, for removal: This API element is subject to removal in a future version.getRoutingPolicy
(com.yahoo.text.Utf8String protocolName, String policyName, String policyParam) Returns a routing policy that corresponds to the argument protocol name, policy name and policy parameter.getRoutingPolicy
(String protocolName, String policyName, String policyParam) Returns a routing policy that corresponds to the argument protocol name, policy name and policy parameter.getRoutingTable
(com.yahoo.text.Utf8String name) Returns a named routing table, may return null.getRoutingTable
(String name) Returns a named routing table, may return null.void
handleMessage
(Message msg) This function is called when a message arrives.void
handleReply
(Reply reply) This function is called when a reply arrives.void
putProtocol
(Protocol protocol) Adds a protocol to the internal repository of protocols, replacing any previous instance of the protocol and clearing the associated routing policy cache.void
void
setMaxPendingCount
(int maxCount) Deprecated, for removal: This API element is subject to removal in a future version.void
setMaxPendingSize
(int maxSize) Deprecated, for removal: This API element is subject to removal in a future version.void
setupRouting
(RoutingSpec spec) Sets the routing specification for this client.void
sync()
Synchronize with internal threads.void
unregisterSession
(String name, boolean broadcastName) This method is invoked by theIntermediateSession.destroy()
to unregister sessions from receiving data from message bus.
-
Constructor Details
-
MessageBus
Convenience constructor that proxies
MessageBus(Network, MessageBusParams)
by adding the given protocols to a defaultMessageBusParams
object.- Parameters:
net
- The network to associate with.protocols
- An array of protocols to register.
-
MessageBus
Constructs an instance of message bus. This requires a network object that it will associate with. This assignment may not change during the lifetime of this message bus, and this bus will be the single owner of this net.
- Parameters:
net
- The network to associate with.params
- The parameters that controls this bus.
-
MessageBus
Constructs an instance of message bus. This requires a network multiplexer that it will associate with. This assignment may not change during the lifetime of this message bus.
- Parameters:
net
- The network multiplexer to associate with.params
- The parameters that controls this bus.
-
-
Method Details
-
register
-
destroy
public boolean destroy()Sets the destroyed flag to true. The very first time this method is called, it cleans up all its dependencies. Even if you retain a reference to this object, all of its content is allowed to be garbage collected.
- Returns:
- True if content existed and was destroyed.
-
sync
public void sync()Synchronize with internal threads. This method will handshake with all internal threads. This has the implicit effect of waiting for all active callbacks. Note that this method should never be invoked from a callback since that would make the thread wait for itself... forever. This method is typically used to untangle during session shutdown.
-
createSourceSession
This is a convenience method to call
createSourceSession(SourceSessionParams)
with default values for theSourceSessionParams
object.- Parameters:
handler
- The reply handler to receive the replies for the session.- Returns:
- The created session.
-
createSourceSession
This is a convenience method to call
createSourceSession(SourceSessionParams)
by first assigning the reply handler to the parameter object.- Parameters:
handler
- The reply handler to receive the replies for the session.params
- The parameters to control the session.- Returns:
- The created session.
-
createSourceSession
Creates a source session on top of this message bus.
- Parameters:
params
- The parameters to control the session.- Returns:
- The created session.
-
createIntermediateSession
public IntermediateSession createIntermediateSession(String name, boolean broadcastName, MessageHandler msgHandler, ReplyHandler replyHandler) This is a convenience method to call
createIntermediateSession(IntermediateSessionParams)
with default values for theIntermediateSessionParams
object.- Parameters:
name
- The local unique name for the created session.broadcastName
- Whether or not to broadcast this session's name on the network.msgHandler
- The handler to receive the messages for the session.replyHandler
- The handler to received the replies for the session.- Returns:
- The created session.
-
createIntermediateSession
Creates an intermediate session on top of this message bus using the given handlers and parameter object.
- Parameters:
params
- The parameters to control the session.- Returns:
- The created session.
-
createDetachedIntermediateSession
-
createDestinationSession
public DestinationSession createDestinationSession(String name, boolean broadcastName, MessageHandler handler) This is a convenience method to call
createDestinationSession(DestinationSessionParams)
with default values for theDestinationSessionParams
object.- Parameters:
name
- The local unique name for the created session.broadcastName
- Whether or not to broadcast this session's name on the network.handler
- The handler to receive the messages for the session.- Returns:
- The created session.
-
createDestinationSession
Creates a destination session on top of this message bus using the given handlers and parameter object.
- Parameters:
params
- The parameters to control the session.- Returns:
- The created session.
-
createDetachedDestinationSession
-
connect
Connects the given session to the network, so it will receive requests. -
unregisterSession
This method is invoked by the
IntermediateSession.destroy()
to unregister sessions from receiving data from message bus.- Parameters:
name
- The name of the session to remove.broadcastName
- Whether or not session name was broadcast.
-
handleMessage
Description copied from interface:MessageHandler
This function is called when a message arrives.- Specified by:
handleMessage
in interfaceMessageHandler
- Parameters:
msg
- The message that arrived.
-
handleReply
Description copied from interface:ReplyHandler
This function is called when a reply arrives.- Specified by:
handleReply
in interfaceReplyHandler
- Parameters:
reply
- The reply that arrived.
-
deliverMessage
Description copied from interface:NetworkOwner
All messages that arrive in the network layer is passed to its owner through this function.- Specified by:
deliverMessage
in interfaceNetworkOwner
- Parameters:
msg
- The message that just arrived from the network.session
- The name of the session that is the recipient of the request.
-
putProtocol
Adds a protocol to the internal repository of protocols, replacing any previous instance of the protocol and clearing the associated routing policy cache.
- Parameters:
protocol
- The protocol to add.
-
getProtocol
Description copied from interface:NetworkOwner
All messages are sent across the network with its accompanying protocol name so that it can be decoded at the receiving end. The network queries its owner through this function to resolve the protocol from its name.- Specified by:
getProtocol
in interfaceNetworkOwner
- Parameters:
name
- The name of the protocol to return.- Returns:
- The named protocol.
-
deliverReply
-
setupRouting
Description copied from interface:ConfigHandler
Sets the routing specification for this client. This will be done synchronously during initialization, and then subsequently whenever an updated configuration is available.- Specified by:
setupRouting
in interfaceConfigHandler
- Parameters:
spec
- The routing specification.
-
getResender
Deprecated, for removal: This API element is subject to removal in a future version.Returns the resender that is running within this message bus.
- Returns:
- The resender.
-
getPendingCount
Deprecated.Returns the number of messages received that have not been replied to yet.
- Returns:
- The pending count.
-
getPendingSize
Deprecated.Returns the size of messages received that have not been replied to yet.
- Returns:
- The pending size.
-
setMaxPendingCount
Deprecated, for removal: This API element is subject to removal in a future version.Sets the maximum number of messages that can be received without being replied to yet.
- Parameters:
maxCount
- The max count.
-
getMaxPendingCount
Deprecated, for removal: This API element is subject to removal in a future version.Gets maximum number of messages that can be received without being replied to yet. -
setMaxPendingSize
Deprecated, for removal: This API element is subject to removal in a future version.Sets the maximum size of messages that can be received without being replied to yet.
- Parameters:
maxSize
- The max size.
-
getMaxPendingSize
Deprecated, for removal: This API element is subject to removal in a future version.Gets maximum combined size of messages that can be received without being replied to yet. -
getRoutingTable
Returns a named routing table, may return null.
- Parameters:
name
- The name of the routing table to return.- Returns:
- The routing table object.
-
getRoutingTable
Returns a named routing table, may return null.
- Parameters:
name
- The name of the routing table to return.- Returns:
- The routing table object.
-
getRoutingPolicy
Returns a routing policy that corresponds to the argument protocol name, policy name and policy parameter. This will cache reuse all policies as soon as they are first requested.
- Parameters:
protocolName
- The name of the protocol to invokeProtocol.createPolicy(String,String)
on.policyName
- The name of the routing policy to retrieve.policyParam
- The parameter for the routing policy to retrieve.- Returns:
- A corresponding routing policy, or null.
-
getRoutingPolicy
public RoutingPolicy getRoutingPolicy(com.yahoo.text.Utf8String protocolName, String policyName, String policyParam) Returns a routing policy that corresponds to the argument protocol name, policy name and policy parameter. This will cache reuse all policies as soon as they are first requested.
- Parameters:
protocolName
- The name of the protocol to invokeProtocol.createPolicy(String,String)
on.policyName
- The name of the routing policy to retrieve.policyParam
- The parameter for the routing policy to retrieve.- Returns:
- A corresponding routing policy, or null.
-
getConnectionSpec
Returns the connection spec string for the network layer of this message bus. This is merely a proxy of the same function in the network layer.
- Returns:
- The connection string.
-