View Javadoc

1   /*
2    * $Id: Service.java 12247 2008-07-07 21:25:01Z dfeist $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSource, Inc.  All rights reserved.  http://www.mulesource.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  
11  package org.mule.api.service;
12  
13  import org.mule.api.MuleContext;
14  import org.mule.api.MuleEvent;
15  import org.mule.api.MuleException;
16  import org.mule.api.MuleMessage;
17  import org.mule.api.NamedObject;
18  import org.mule.api.component.Component;
19  import org.mule.api.context.MuleContextAware;
20  import org.mule.api.lifecycle.Lifecycle;
21  import org.mule.api.model.Model;
22  import org.mule.api.routing.InboundRouterCollection;
23  import org.mule.api.routing.OutboundRouterCollection;
24  import org.mule.api.routing.ResponseRouterCollection;
25  
26  import java.beans.ExceptionListener;
27  import java.io.Serializable;
28  
29  /**
30   * <code>Service</code> is the internal representation of a Mule Managed service. It
31   * is responsible for managing the interaction of events to and from the service as
32   * well as managing pooled resources.
33   */
34  
35  public interface Service extends Serializable, Lifecycle, MuleContextAware, NamedObject
36  {
37      /**
38       * Makes an asynchronous event call to the service.
39       * 
40       * @param event the event to consume
41       * @throws MuleException if the event fails to be processed
42       */
43      void dispatchEvent(MuleEvent event) throws MuleException;
44  
45      /**
46       * Makes a synchronous event call to the service. This event will be consumed by
47       * the service and a result returned.
48       * 
49       * @param event the event to consume
50       * @return a MuleMessage containing the resulting message and properties
51       * @throws MuleException if the event fails to be processed
52       */
53      MuleMessage sendEvent(MuleEvent event) throws MuleException;
54  
55      /**
56       * Determines whether this service has been started
57       * 
58       * @return true is the service is started and ready to receive events
59       */
60      boolean isStarted();
61  
62      /**
63       * Pauses event processing for a single Mule Service. Unlike stop(), a paused
64       * service will still consume messages from the underlying transport, but those
65       * messages will be queued until the service is resumed.
66       */
67      void pause() throws MuleException;
68  
69      /**
70       * Resumes a single Mule Service that has been paused. If the service is not
71       * paused nothing is executed.
72       */
73      void resume() throws MuleException;
74  
75      /**
76       * True if the service is in a paused state, false otherwise
77       * 
78       * @return True if the service is in a paused state, false otherwise
79       */
80      boolean isPaused();
81      
82      /**
83       * The exception strategy to use to handle exceptions in the Mule UMO.
84       *
85       * @return the exception strategy to use. If none has been set a default will be
86       *         used.
87       */
88      ExceptionListener getExceptionListener();
89  
90      /**
91       * Inbound Routers control how events are received by a service. If no router is
92       * set. A default will be used that uses the inboundProvider set on his
93       * descriptor.
94       * 
95       * @return the inbound router for this service. This will always return a valid
96       *         router.
97       * @see InboundRouterCollection
98       */
99      InboundRouterCollection getInboundRouter();
100 
101     /**
102      * Outbound Routers control how events are published by a service once. the
103      * event has been processed. If no router is set. A default will be used that
104      * uses the outboundProvider set on his descriptor to route the event.
105      *
106      * @return the outbound router for this service
107      * @see OutboundRouterCollection
108      */
109     OutboundRouterCollection getOutboundRouter();
110 
111     /**
112      * Response Routers control how events are returned in a request/response call.
113      * It can be use to aggregate response events before returning, thus acting as a
114      * Join in a forked process. This can be used to make request/response calls a
115      * lot more efficient as independent tasks can be forked, execute concurrently
116      * and then join before the request completes
117      *
118      * @return the response router for this service
119      * @see ResponseRouterCollection
120      */
121     ResponseRouterCollection getResponseRouter();
122 
123     /**
124      * Returns the initial state of this service
125      *
126      * @return the initial state of this service
127      */
128     String getInitialState();
129 
130     /**
131      * Returns the name of the model that this descriptor is registered with.
132      * @return the name of the model that this descriptor is registered with or null
133      *         if this descriptor has not been registered with a model yet
134      */
135     Model getModel();
136 
137     /**
138      * The exception strategy to use to handle exceptions in the Mule UMO.
139      * 
140      * @param listener the exception strategy to use. If none has been set or
141      *            argument is null a default
142      */
143     void setExceptionListener(ExceptionListener listener);
144 
145     /**
146      * Inbound Routers control how events are received by a service. If no router is
147      * set. A default will be used that uses the inboundProvider set on his
148      * descriptor.
149      *
150      * @param router the inbound router for this service
151      * @see InboundRouterCollection
152      */
153     void setInboundRouter(InboundRouterCollection router);
154 
155     /**
156      * Outbound Routers control how events are published by a service once. the
157      * event has been processed. If no router is set. A default will be used that
158      * uses the outboundProvider set on his descriptor to route the event.
159      *
160      * @param router the outbound router for this service
161      * @see OutboundRouterCollection
162      */
163     void setOutboundRouter(OutboundRouterCollection router);
164 
165     /**
166      * Response Routers control how events are returned in a request/response call.
167      * It can be use to aggregate response events before returning, thus acting as a
168      * Join in a forked process. This can be used to make request/response calls a
169      * lot more efficient as independent tasks can be forked, execute concurrently
170      * and then join before the request completes
171      *
172      * @param router the response router for this service
173      * @see org.mule.api.routing.ResponseRouterCollection
174      */
175     void setResponseRouter(ResponseRouterCollection router);
176 
177     /**
178      * Sets the initial state of this service
179      *
180      * @param state the initial state of this service
181      * @see org.mule.ImmutableMuleDescriptor#INITIAL_STATE_STARTED
182      * @see org.mule.ImmutableMuleDescriptor#INITIAL_STATE_STOPPED
183      * @see org.mule.ImmutableMuleDescriptor#INITIAL_STATE_PAUSED
184      */
185     void setInitialState(String state);
186 
187     /**
188      * Sets the Model name that this descriptor is registered within.
189      * @param modelName name of the model
190      */
191     void setModel(Model model);
192 
193     /**
194      * Returns the Component that is a invoked by a {@link Service} for each incoming
195      * {@link MuleEvent} routed on by the {@link InboundRouterCollection}.
196      * 
197      * @return
198      */
199     Component getComponent();
200 
201     /**
202      * Sets the Component that is a invoked by a {@link Service} for each incoming
203      * {@link MuleEvent} routed on by the {@link InboundRouterCollection}.
204      * 
205      * @param component
206      */
207     void setComponent(Component component);
208     
209     MuleContext getMuleContext();
210 
211 }