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 }