org.mule.extras.client
Class MuleClient

java.lang.Object
  extended byorg.mule.extras.client.MuleClient

public class MuleClient
extends java.lang.Object

MuleClient is a simple interface for Mule clients to send and receive events from a Mule Server. In most Mule applications events are triggered by some external occurrence such as a messge being received on a queue or file being copied to a directory. The Mule client allows the user to send and receive events programmatically through its Api.

The client defines a UMOEndpointURI which is used to determine how a message is sent of received. The url defines the protocol, the endpointUri destination of the message and optionally the endpoint to use when dispatching the event. For example -

vm://my.object dispatches to a my.object destination using the VM endpoint. There needs to be a global Vm endpoint registered for the message to be sent

jms://jmsProvider/orders.topic dispatches a jms message via the globally registered jmsProvider over a topic destination called orders.topic.

jms://orders.topic Is equivilent to the above except that the endpoint is determined by the protocol, so the first jms endpoint is used.

Note that there must be a configured MuleManager for this client to work. It will use the one available using MuleManager.getInstance()

Version:
$Revision: 1.5 $
Author:
Ross Mason
See Also:
MuleEndpointURI

Field Summary
protected static Log logger
          logger used by this class
 
Constructor Summary
MuleClient()
          Creates a default Mule client that will use the default serverEndpoint to connect to a remote server instance.
MuleClient(boolean synchronous)
           
MuleClient(boolean synchronous, java.lang.String user, java.lang.String password)
           
MuleClient(java.lang.String user, java.lang.String password)
           
 
Method Summary
 void close()
          Distroys any resources created by this client session
 void dispatch(java.lang.String url, java.lang.Object payload, java.util.Map messageProperties)
          Dispatches an event asynchronously to a endpointUri via a mule server.
 void dispatchDirect(java.lang.String component, java.lang.Object payload, java.util.Map messageProperties)
          dispatches an event asynchronously to the components
protected  UMOEndpoint getDefaultClientProvider(UMODescriptor descriptor, java.lang.Object payload)
           
protected  UMOEvent getEvent(UMOMessage message, UMOEndpointURI uri, boolean synchronous)
          Packages a mule event for the current request
 UMOManager getManager()
          Overriding methods may want to return a custom manager here
 RemoteDispatcher getRemoteDispatcher(java.lang.String serverEndpoint)
           
 RemoteDispatcher getRemoteDispatcher(java.lang.String serverEndpoint, java.lang.String user, java.lang.String password)
           
 UMOMessage receive(java.lang.String url, long timeout)
          Will receive an event from an endpointUri determined by the url
 UMOMessage receive(java.lang.String url, java.lang.String transformers, long timeout)
          Will receive an event from an endpointUri determined by the url
 UMOMessage receive(java.lang.String url, UMOTransformer transformer, long timeout)
          Will receive an event from an endpointUri determined by the url
 void registerComponent(java.lang.Object component, java.lang.String name, MuleEndpointURI listenerEndpoint)
          Registers a java object as a Umo pcomponent that listens for events on the given url.
 void registerComponent(java.lang.Object component, java.lang.String name, MuleEndpointURI listenerEndpoint, MuleEndpointURI sendEndpoint)
          Registers a java object as a Umo pcomponent that listens for and sends events on the given urls.
 void registerComponent(UMODescriptor descriptor)
          Registers a user configured MuleDescriptor of a components to the server.
 UMOMessage send(java.lang.String url, java.lang.Object payload, java.util.Map messageProperties)
          Sends an event synchronously to a endpointUri via a mule server and a resulting message is returned.
 UMOMessage send(java.lang.String url, java.lang.Object payload, java.util.Map messageProperties, int timeout)
          Sends an event synchronously to a endpointUri via a mule server and a resulting message is returned.
 FutureMessageResult sendAsync(java.lang.String url, java.lang.Object payload, java.util.Map messageProperties)
          sends an event request to a Url, making the result of the event trigger available as a Future result that can be accessed later by client code.
 FutureMessageResult sendAsync(java.lang.String url, java.lang.Object payload, java.util.Map messageProperties, int timeout)
          sends an event request to a Url, making the result of the event trigger available as a Future result that can be accessed later by client code.
 UMOMessage sendDirect(java.lang.String component, java.lang.String transformers, java.lang.Object payload, java.util.Map messageProperties)
          sends an event synchronously to a components
 FutureMessageResult sendDirectAsync(java.lang.String component, java.lang.String transformers, java.lang.Object payload, java.util.Map messageProperties)
          sends an event to a components on a local Mule instance, while making the result of the event trigger available as a Future result that can be accessed later by client code.
 void sendNoReceive(java.lang.String url, java.lang.Object payload, java.util.Map messageProperties)
          Sends an event synchronously to a endpointUri via a mule server without waiting for the result.
 void shutdownServer()
           
 void unregisterComponent(java.lang.String name)
          Unregisters a previously register components.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected static transient Log logger
logger used by this class

Constructor Detail

MuleClient

public MuleClient()
           throws UMOException
Creates a default Mule client that will use the default serverEndpoint to connect to a remote server instance.

Throws:
UMOException

MuleClient

public MuleClient(java.lang.String user,
                  java.lang.String password)
           throws UMOException

MuleClient

public MuleClient(boolean synchronous)
           throws UMOException

MuleClient

public MuleClient(boolean synchronous,
                  java.lang.String user,
                  java.lang.String password)
           throws UMOException
Method Detail

dispatch

public void dispatch(java.lang.String url,
                     java.lang.Object payload,
                     java.util.Map messageProperties)
              throws UMOException
Dispatches an event asynchronously to a endpointUri via a mule server. the Url determines where to dispathc the event to, this can be in the form of

Parameters:
url - the Mule url used to determine the destination and transport of the message
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. In the case of Jms you could set the JMSReplyTo property in these properties.
Throws:
UMOException

sendDirect

public UMOMessage sendDirect(java.lang.String component,
                             java.lang.String transformers,
                             java.lang.Object payload,
                             java.util.Map messageProperties)
                      throws UMOException
sends an event synchronously to a components

Parameters:
component - the name of the Mule components to send to
transformers - a comma separated list of transformers to apply to the result message
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. as null
Returns:
the result message if any of the invocation
Throws:
UMOException - if the dispatch fails or the components or transfromers cannot be found

dispatchDirect

public void dispatchDirect(java.lang.String component,
                           java.lang.Object payload,
                           java.util.Map messageProperties)
                    throws UMOException
dispatches an event asynchronously to the components

Parameters:
component - the name of the Mule components to dispatch to
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. as null
Throws:
UMOException - if the dispatch fails or the components or transfromers cannot be found

sendAsync

public FutureMessageResult sendAsync(java.lang.String url,
                                     java.lang.Object payload,
                                     java.util.Map messageProperties)
                              throws UMOException
sends an event request to a Url, making the result of the event trigger available as a Future result that can be accessed later by client code.

Parameters:
url - the url to make a request on
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. as null
Returns:
the result message if any of the invocation
Throws:
UMOException - if the dispatch fails or the components or transfromers cannot be found

sendAsync

public FutureMessageResult sendAsync(java.lang.String url,
                                     java.lang.Object payload,
                                     java.util.Map messageProperties,
                                     int timeout)
                              throws UMOException
sends an event request to a Url, making the result of the event trigger available as a Future result that can be accessed later by client code.

Parameters:
url - the url to make a request on
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. as null
timeout - how long to block in milliseconds waiting for a result
Returns:
the result message if any of the invocation
Throws:
UMOException - if the dispatch fails or the components or transfromers cannot be found

sendDirectAsync

public FutureMessageResult sendDirectAsync(java.lang.String component,
                                           java.lang.String transformers,
                                           java.lang.Object payload,
                                           java.util.Map messageProperties)
                                    throws UMOException
sends an event to a components on a local Mule instance, while making the result of the event trigger available as a Future result that can be accessed later by client code. If forwardDirectRequests flag s set and the components is not found on the local Mule instance it will forward to a remote server. Users can endpoint a url to a remote Mule server in the constructor of a Mule client, by default the default Mule server url tcp://localhost:60504 is used.

Parameters:
component - the name of the Mule components to send to
transformers - a comma separated list of transformers to apply to the result message
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. as null
Returns:
the result message if any of the invocation
Throws:
UMOException - if the dispatch fails or the components or transfromers cannot be found

send

public UMOMessage send(java.lang.String url,
                       java.lang.Object payload,
                       java.util.Map messageProperties)
                throws UMOException
Sends an event synchronously to a endpointUri via a mule server and a resulting message is returned.

Parameters:
url - the Mule url used to determine the destination and transport of the message
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. In the case of Jms you could set the JMSReplyTo property in these properties.
Returns:
A return message, this could be null if the the components invoked explicitly sets a return as null
Throws:
UMOException

send

public UMOMessage send(java.lang.String url,
                       java.lang.Object payload,
                       java.util.Map messageProperties,
                       int timeout)
                throws UMOException
Sends an event synchronously to a endpointUri via a mule server and a resulting message is returned.

Parameters:
url - the Mule url used to determine the destination and transport of the message
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. In the case of Jms you could set the JMSReplyTo property in these properties.
timeout - The time in milliseconds the the call should block waiting for a response
Returns:
A return message, this could be null if the the components invoked explicitly sets a return as null
Throws:
UMOException

receive

public UMOMessage receive(java.lang.String url,
                          long timeout)
                   throws UMOException
Will receive an event from an endpointUri determined by the url

Parameters:
url - the Mule url used to determine the destination and transport of the message
timeout - how long to block waiting to receive the event, if set to 0 the receive will not wait at all and if set to -1 the receive will wait forever
Returns:
the message received or null if no message was received
Throws:
UMOException

receive

public UMOMessage receive(java.lang.String url,
                          java.lang.String transformers,
                          long timeout)
                   throws UMOException
Will receive an event from an endpointUri determined by the url

Parameters:
url - the Mule url used to determine the destination and transport of the message
transformers - A comma separated list of transformers used to apply to the result message
timeout - how long to block waiting to receive the event, if set to 0 the receive will not wait at all and if set to -1 the receive will wait forever
Returns:
the message received or null if no message was received
Throws:
UMOException

receive

public UMOMessage receive(java.lang.String url,
                          UMOTransformer transformer,
                          long timeout)
                   throws UMOException
Will receive an event from an endpointUri determined by the url

Parameters:
url - the Mule url used to determine the destination and transport of the message
transformer - A transformer used to apply to the result message
timeout - how long to block waiting to receive the event, if set to 0 the receive will not wait at all and if set to -1 the receive will wait forever
Returns:
the message received or null if no message was received
Throws:
UMOException

getEvent

protected UMOEvent getEvent(UMOMessage message,
                            UMOEndpointURI uri,
                            boolean synchronous)
                     throws UMOException
Packages a mule event for the current request

Parameters:
message - the event payload
uri - the destination endpointUri
synchronous - whether the event will be synchronously processed
Returns:
the UMOEvent
Throws:
UMOException

getDefaultClientProvider

protected UMOEndpoint getDefaultClientProvider(UMODescriptor descriptor,
                                               java.lang.Object payload)
                                        throws MuleClientException,
                                               UMOException
Throws:
MuleClientException
UMOException

sendNoReceive

public void sendNoReceive(java.lang.String url,
                          java.lang.Object payload,
                          java.util.Map messageProperties)
                   throws UMOException
Sends an event synchronously to a endpointUri via a mule server without waiting for the result.

Parameters:
url - the Mule url used to determine the destination and transport of the message
payload - the object that is the payload of the event
messageProperties - any properties to be associated with the payload. In the case of Jms you could set the JMSReplyTo property in these properties.
Throws:
UMOException

getManager

public UMOManager getManager()
Overriding methods may want to return a custom manager here

Returns:
the UMOManager to use

registerComponent

public void registerComponent(java.lang.Object component,
                              java.lang.String name,
                              MuleEndpointURI listenerEndpoint)
                       throws UMOException
Registers a java object as a Umo pcomponent that listens for events on the given url. By default the ThreadingProfile for the components will be set so that there will only be one thread of execution.

Parameters:
component - any java object, Mule will it's endpointUri discovery to determine which event to invoke based on the evnet payload type
name - The identifying name of the components. This can be used to later unregister it
listenerEndpoint - The url endpointUri to listen to
Throws:
UMOException

registerComponent

public void registerComponent(java.lang.Object component,
                              java.lang.String name,
                              MuleEndpointURI listenerEndpoint,
                              MuleEndpointURI sendEndpoint)
                       throws UMOException
Registers a java object as a Umo pcomponent that listens for and sends events on the given urls. By default the ThreadingProfile for the components will be set so that there will only be one thread of execution.

Parameters:
component - any java object, Mule will it's endpointUri discovery to determine which event to invoke based on the evnet payload type
name - The identifying name of the components. This can be used to later unregister it
listenerEndpoint - The url endpointUri to listen to
sendEndpoint - The url endpointUri to dispatch to
Throws:
UMOException

registerComponent

public void registerComponent(UMODescriptor descriptor)
                       throws UMOException
Registers a user configured MuleDescriptor of a components to the server. If users want to register object instances with the server rather than class names that get created at runtime or reference to objects in the container, the user must call the descriptors setImplementationInstance() method - MyBean implementation = new MyBean(); descriptor.setImplementationInstance(implementation); Calling this method is equivilent to calling UMOModel.registerComponent(..)

Parameters:
descriptor - the componet descriptor to register
Throws:
UMOException - the descriptor is invalid or cannot be initialised or started
See Also:
UMOModel

unregisterComponent

public void unregisterComponent(java.lang.String name)
                         throws UMOException
Unregisters a previously register components. This will also unregister any listeners for the components Calling this method is equivilent to calling UMOModel.unregisterComponent(..)

Parameters:
name - the name of the componet to unregister
Throws:
UMOException - if unregistering the components fails, i.e. The underlying transport fails to unregister a listener. If the components does not exist, this method should not throw an exception.
See Also:
UMOModel

close

public void close()
           throws UMOException
Distroys any resources created by this client session

Throws:
UMOException

getRemoteDispatcher

public RemoteDispatcher getRemoteDispatcher(java.lang.String serverEndpoint)
                                     throws MalformedEndpointException
Throws:
MalformedEndpointException

getRemoteDispatcher

public RemoteDispatcher getRemoteDispatcher(java.lang.String serverEndpoint,
                                            java.lang.String user,
                                            java.lang.String password)
                                     throws MalformedEndpointException
Throws:
MalformedEndpointException

shutdownServer

public void shutdownServer()


Copyright © 2003-2005 SymphonySoft Limited. All Rights Reserved.