org.mule.module.client
Class MuleClient

java.lang.Object
  extended by org.mule.module.client.MuleClient
All Implemented Interfaces:
Disposable

public class MuleClient
extends Object
implements Disposable

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 message being received on a queue or a 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 EndpointURI 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 equivalent 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 muleContext

See Also:
MuleEndpointURI

Field Summary
protected static Log logger
          logger used by this class
 
Fields inherited from interface org.mule.api.lifecycle.Disposable
PHASE_NAME
 
Constructor Summary
MuleClient()
          Creates a Mule client that will use the default serverEndpoint when connecting to a remote server instance.
MuleClient(boolean startContext)
           
MuleClient(MuleContext context)
           
MuleClient(String configResources)
          Configures a Mule client instance using the the default SpringXmlConfigurationBuilder to parse configResources.
MuleClient(String configResources, ConfigurationBuilder builder)
          Configures a Mule client instance
MuleClient(String configResources, ConfigurationBuilder builder, String user, String password)
          Configures a Mule client instance
MuleClient(String user, String password)
          Configures a new Mule client and either uses an existing Manager running in this JVM or creates a new empty MuleContext
 
Method Summary
 void dispatch(String url, MuleMessage message)
          Dispatches an event asynchronously to a endpointUri via a Mule server.
 void dispatch(String url, Object payload, Map messageProperties)
          Dispatches an event asynchronously to a endpointUri via a Mule server.
 void dispatchDirect(String componentName, MuleMessage message)
          Dispatches an event asynchronously to a component
 void dispatchDirect(String component, Object payload, Map messageProperties)
          Dispatches an event asynchronously to a component
 void dispose()
          Will dispose the MuleManager instance if a new instance was created for this client.
 MuleConfiguration getConfiguration()
           
protected  ImmutableEndpoint getDefaultClientEndpoint(Service service, Object payload)
           
protected  MuleEvent getEvent(MuleMessage message, String uri, boolean synchronous)
          Packages a mule event for the current request
protected  InboundEndpoint getInboundEndpoint(String uri)
           
 MuleContext getMuleContext()
          The overriding method may want to return a custom MuleContext here
protected  OutboundEndpoint getOutboundEndpoint(String uri)
           
 Object getProperty(String key)
           
 RemoteDispatcher getRemoteDispatcher(String serverEndpoint)
           
 RemoteDispatcher getRemoteDispatcher(String serverEndpoint, String user, String password)
           
 void registerComponent(Object component, String name, EndpointURI listenerEndpoint)
          Deprecated. Use the RegistryContext to get the registry and register the service there
 void registerComponent(Object component, String name, MuleEndpointURI listenerEndpoint, MuleEndpointURI sendEndpoint)
          Deprecated. Use the RegistryContext to get the registry and register the service there
 MuleMessage request(String url, List transformers, long timeout)
          Will receive an event from an endpointUri determined by the URL
 MuleMessage request(String url, long timeout)
          Will receive an event from an endpointUri determined by the URL.
 MuleMessage request(String url, String transformers, long timeout)
          Will receive an event from an endpointUri determined by the URL
 MuleMessage send(String url, MuleMessage message)
          Sends an event synchronously to a endpointUri via a Mule server and a resulting message is returned.
 MuleMessage send(String url, MuleMessage message, int timeout)
          Sends an event synchronously to a endpointUri via a mule server and a resulting message is returned.
 MuleMessage send(String url, Object payload, Map messageProperties)
          Sends an event synchronously to a endpointUri via a Mule server and a resulting message is returned.
 MuleMessage send(String url, Object payload, Map messageProperties, int timeout)
          Sends an event synchronously to a endpointUri via a mule server and a resulting message is returned.
 FutureMessageResult sendAsync(String url, MuleMessage message)
          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(String url, MuleMessage message, 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.
 FutureMessageResult sendAsync(String url, Object payload, 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(String url, Object payload, 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.
 MuleMessage sendDirect(String componentName, String transformers, MuleMessage message)
          Sends an event synchronously to a component
 MuleMessage sendDirect(String component, String transformers, Object payload, Map messageProperties)
          Sends an event synchronously to a component
 FutureMessageResult sendDirectAsync(String component, String transformers, MuleMessage message)
          Snds an event to a component 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.
 FutureMessageResult sendDirectAsync(String component, String transformers, Object payload, Map messageProperties)
          Sends an event to a component 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(String url, Object payload, Map messageProperties)
          Sends an event synchronously to a endpointUri via a Mule server without waiting for the result.
 void setProperty(String key, Object value)
           
 void unregisterComponent(String name)
          Deprecated. Use the RegistryContext to get the registry and unregister the service there
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected static final Log logger
logger used by this class

Constructor Detail

MuleClient

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

Throws:
MuleException

MuleClient

public MuleClient(boolean startContext)
           throws MuleException
Throws:
MuleException

MuleClient

public MuleClient(MuleContext context)
           throws MuleException
Throws:
MuleException

MuleClient

public MuleClient(String configResources)
           throws MuleException
Configures a Mule client instance using the the default SpringXmlConfigurationBuilder to parse configResources.

Parameters:
configResources - a config resource location to configure this client with
Throws:
ConfigurationException - if there is a MuleContext instance already running in this JVM or if the builder fails to configure the Manager
MuleException

MuleClient

public MuleClient(String user,
                  String password)
           throws MuleException
Configures a new Mule client and either uses an existing Manager running in this JVM or creates a new empty MuleContext

Parameters:
user - the username to use when connecting to a remote server instance
password - the password for the user
Throws:
MuleException

MuleClient

public MuleClient(String configResources,
                  ConfigurationBuilder builder)
           throws ConfigurationException,
                  InitialisationException
Configures a Mule client instance

Parameters:
configResources - a config resource location to configure this client with
builder - the configuration builder to use
Throws:
ConfigurationException - is there is a MuleContext instance already running in this JVM or if the builder fails to configure the Manager
InitialisationException

MuleClient

public MuleClient(String configResources,
                  ConfigurationBuilder builder,
                  String user,
                  String password)
           throws ConfigurationException,
                  InitialisationException
Configures a Mule client instance

Parameters:
configResources - a config resource location to configure this client with
builder - the configuration builder to use
user - the username to use when connecting to a remote server instance
password - the password for the user
Throws:
ConfigurationException - is there is a MuleContext instance already running in this JVM or if the builder fails to configure the Manager
InitialisationException
Method Detail

dispatch

public void dispatch(String url,
                     Object payload,
                     Map messageProperties)
              throws MuleException
Dispatches an event asynchronously to a endpointUri via a Mule server. The URL determines where to dispatch the event to.

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:
MuleException

dispatch

public void dispatch(String url,
                     MuleMessage message)
              throws MuleException
Dispatches an event asynchronously to a endpointUri via a Mule server. The URL determines where to dispatch the event to.

Parameters:
url - the Mule URL used to determine the destination and transport of the message
message - the message to send
Throws:
MuleException

sendDirect

public MuleMessage sendDirect(String component,
                              String transformers,
                              Object payload,
                              Map messageProperties)
                       throws MuleException
Sends an event synchronously to a component

Parameters:
component - the name of the Mule component 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:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendDirect

public MuleMessage sendDirect(String componentName,
                              String transformers,
                              MuleMessage message)
                       throws MuleException
Sends an event synchronously to a component

Parameters:
componentName - the name of the Mule component to send to
transformers - a comma separated list of transformers to apply to the result message
message - the message to send
Returns:
the result message if any of the invocation
Throws:
MuleException - if the dispatch fails or the components or transfromers cannot be found

dispatchDirect

public void dispatchDirect(String component,
                           Object payload,
                           Map messageProperties)
                    throws MuleException
Dispatches an event asynchronously to a component

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:
MuleException - if the dispatch fails or the components or transfromers cannot be found

dispatchDirect

public void dispatchDirect(String componentName,
                           MuleMessage message)
                    throws MuleException
Dispatches an event asynchronously to a component

Parameters:
componentName - the name of the Mule components to dispatch to
message - the message to send
Throws:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendAsync

public FutureMessageResult sendAsync(String url,
                                     Object payload,
                                     Map messageProperties)
                              throws MuleException
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:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendAsync

public FutureMessageResult sendAsync(String url,
                                     MuleMessage message)
                              throws MuleException
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
message - the message to send
Returns:
the result message if any of the invocation
Throws:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendAsync

public FutureMessageResult sendAsync(String url,
                                     Object payload,
                                     Map messageProperties,
                                     int timeout)
                              throws MuleException
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:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendAsync

public FutureMessageResult sendAsync(String url,
                                     MuleMessage message,
                                     int timeout)
                              throws MuleException
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
message - the message to send
timeout - how long to block in milliseconds waiting for a result
Returns:
the result message if any of the invocation
Throws:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendDirectAsync

public FutureMessageResult sendDirectAsync(String component,
                                           String transformers,
                                           Object payload,
                                           Map messageProperties)
                                    throws MuleException
Sends an event to a component 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. Users can specify 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.
Returns:
the result message if any of the invocation
Throws:
MuleException - if the dispatch fails or the components or transfromers cannot be found

sendDirectAsync

public FutureMessageResult sendDirectAsync(String component,
                                           String transformers,
                                           MuleMessage message)
                                    throws MuleException
Snds an event to a component 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. Users can specify 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
message - the message to send
Returns:
the result message if any of the invocation
Throws:
MuleException - if the dispatch fails or the components or transfromers cannot be found

send

public MuleMessage send(String url,
                        Object payload,
                        Map messageProperties)
                 throws MuleException
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:
MuleException

send

public MuleMessage send(String url,
                        MuleMessage message)
                 throws MuleException
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
message - the Message for the event
Returns:
A return message, this could be null if the the components invoked explicitly sets a return as null.
Throws:
MuleException

send

public MuleMessage send(String url,
                        Object payload,
                        Map messageProperties,
                        int timeout)
                 throws MuleException
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:
MuleException

send

public MuleMessage send(String url,
                        MuleMessage message,
                        int timeout)
                 throws MuleException
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
message - The message to send
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:
MuleException

request

public MuleMessage request(String url,
                           long timeout)
                    throws MuleException
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:
MuleException

request

public MuleMessage request(String url,
                           String transformers,
                           long timeout)
                    throws MuleException
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:
MuleException

request

public MuleMessage request(String url,
                           List transformers,
                           long timeout)
                    throws MuleException
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 - Transformers used to modify 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:
MuleException

getEvent

protected MuleEvent getEvent(MuleMessage message,
                             String uri,
                             boolean synchronous)
                      throws MuleException
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 MuleEvent
Throws:
MuleException

getInboundEndpoint

protected InboundEndpoint getInboundEndpoint(String uri)
                                      throws MuleException
Throws:
MuleException

getOutboundEndpoint

protected OutboundEndpoint getOutboundEndpoint(String uri)
                                        throws MuleException
Throws:
MuleException

getDefaultClientEndpoint

protected ImmutableEndpoint getDefaultClientEndpoint(Service service,
                                                     Object payload)
                                              throws MuleException
Throws:
MuleException

sendNoReceive

public void sendNoReceive(String url,
                          Object payload,
                          Map messageProperties)
                   throws MuleException
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:
MuleException

getMuleContext

public MuleContext getMuleContext()
The overriding method may want to return a custom MuleContext here

Returns:
the MuleContext to use

registerComponent

public void registerComponent(Object component,
                              String name,
                              EndpointURI listenerEndpoint)
                       throws MuleException
Deprecated. Use the RegistryContext to get the registry and register the service there

Registers a Java object as a component 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:
MuleException

registerComponent

public void registerComponent(Object component,
                              String name,
                              MuleEndpointURI listenerEndpoint,
                              MuleEndpointURI sendEndpoint)
                       throws MuleException
Deprecated. Use the RegistryContext to get the registry and register the service there

Registers a Java object as a component 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:
MuleException

unregisterComponent

public void unregisterComponent(String name)
                         throws MuleException
Deprecated. Use the RegistryContext to get the registry and unregister the service there

Unregisters a previously register components. This will also unregister any listeners for the components Calling this method is equivilent to calling Model.unregisterComponent(..)

Parameters:
name - the name of the componet to unregister
Throws:
MuleException - 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:
Model

getRemoteDispatcher

public RemoteDispatcher getRemoteDispatcher(String serverEndpoint)
                                     throws MuleException
Throws:
MuleException

getRemoteDispatcher

public RemoteDispatcher getRemoteDispatcher(String serverEndpoint,
                                            String user,
                                            String password)
                                     throws MuleException
Throws:
MuleException

dispose

public void dispose()
Will dispose the MuleManager instance if a new instance was created for this client. Otherwise this method only cleans up resources no longer needed

Specified by:
dispose in interface Disposable

setProperty

public void setProperty(String key,
                        Object value)

getProperty

public Object getProperty(String key)

getConfiguration

public MuleConfiguration getConfiguration()


Copyright © 2003-2009 MuleSource, Inc.. All Rights Reserved.