View Javadoc

1   /*
2    * $Id: MuleRegistry.java 21610 2011-03-28 09:52:05Z dirk.olmes $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.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.registry;
12  
13  import org.mule.api.MuleContext;
14  import org.mule.api.MuleException;
15  import org.mule.api.agent.Agent;
16  import org.mule.api.construct.FlowConstruct;
17  import org.mule.api.endpoint.EndpointBuilder;
18  import org.mule.api.endpoint.EndpointFactory;
19  import org.mule.api.endpoint.ImmutableEndpoint;
20  import org.mule.api.model.Model;
21  import org.mule.api.service.Service;
22  import org.mule.api.transformer.DataType;
23  import org.mule.api.transformer.Transformer;
24  import org.mule.api.transformer.TransformerException;
25  import org.mule.api.transport.Connector;
26  
27  import java.util.Collection;
28  import java.util.List;
29  import java.util.Properties;
30  
31  /**
32   * Adds lookup/register/unregister methods for Mule-specific entities to the standard
33   * Registry interface.
34   */
35  public interface MuleRegistry extends Registry
36  {
37  
38      /**
39       * Pass this flag as metadata of the {@link Registry#registerObject(String, Object, Object)}  method to have lifecycle
40       * method calls on the registered objects omitted. Unless extending Mule, one will
41       * probably never have a use for this.
42       *
43       * @see Registry#registerObject(String, Object, Object)
44       */
45      public static final int LIFECYCLE_BYPASS_FLAG = 0x01;
46  
47      /**
48       * Determines whether Inject processors should get executed on an object added to the registry
49       * Inject processors are responsible for processing inject interfaces such as {@link org.mule.api.context.MuleContextAware}
50       */
51      public static final int INJECT_PROCESSORS_BYPASS_FLAG = 0x02;
52  
53      /**
54       * Determines whether pre-init processors should get executed on an object added to the registry.
55       * Pre init processors are basically object processors that do not inject members into objects.  These
56       * processors happen after the inject processors
57       */
58      public static final int PRE_INIT_PROCESSORS_BYPASS_FLAG = 0x04;
59  
60      // /////////////////////////////////////////////////////////////////////////
61      // Lookup methods - these should NOT create a new object, only return existing ones
62      // /////////////////////////////////////////////////////////////////////////
63  
64      Connector lookupConnector(String name);
65  
66      /**
67       * Looks-up endpoint builders which can be used to repeatably create endpoints with the same configuration.
68       * These endpoint builder are either global endpoints or they are builders used to create named
69       * endpoints configured on routers and exception strategies.
70       *
71       * @param name the name of the endpointBuilder to find
72       * @return An endpointBuilder with the name specified or null if there is no endpoint builder with that name
73       */
74      EndpointBuilder lookupEndpointBuilder(String name);
75  
76      /**
77       * @deprecated use {@link MuleContext#getEndpointFactory()} instead
78       */
79      @Deprecated
80      EndpointFactory lookupEndpointFactory();
81  
82      Transformer lookupTransformer(String name);
83  
84      Service lookupService(String name);
85  
86      FlowConstruct lookupFlowConstruct(String name);
87  
88      /**
89       * This method will return a list of {@link org.mule.api.transformer.Transformer} objects that accept the given
90       * input and return the given output type of object
91       *
92       * @param input  The  desiered input type for the transformer
93       * @param output the desired output type for the transformer
94       * @return a list of matching transformers. If there were no matchers an empty list is returned.
95       * @deprecated use {@link #lookupTransformers(org.mule.api.transformer.DataType, org.mule.api.transformer.DataType)} instead
96       */
97      @Deprecated
98      List<Transformer> lookupTransformers(Class<?> input, Class<?> output);
99  
100     /**
101      * This method will return a list of {@link org.mule.api.transformer.Transformer} objects that accept the given
102      * input and return the given output type of object
103      *
104      * @param source The  desired input type for the transformer
105      * @param result the desired output type for the transformer
106      * @return a list of matching transformers. If there were no matchers an empty list is returned.
107      * @since 3.0.0
108      */
109     List<Transformer> lookupTransformers(DataType<?> source, DataType<?> result);
110 
111     /**
112      * Will find a transformer that is the closest match to the desired input and output.
113      *
114      * @param input  The  desiered input type for the transformer
115      * @param output the desired output type for the transformer
116      * @return A transformer that exactly matches or the will accept the input and output parameters
117      * @throws TransformerException will be thrown if there is more than one match
118      * @deprecated use {@link #lookupTransformer(org.mule.api.transformer.DataType, org.mule.api.transformer.DataType)} instead
119      */
120     @Deprecated
121     Transformer lookupTransformer(Class<?> input, Class<?> output) throws TransformerException;
122 
123     /**
124      * Will find a transformer that is the closest match to the desired input and output.
125      *
126      * @param source The  desiered input type for the transformer
127      * @param result the desired output type for the transformer
128      * @return A transformer that exactly matches or the will accept the input and output parameters
129      * @throws TransformerException will be thrown if there is more than one match
130      * @since 3.0.0
131      */
132     Transformer lookupTransformer(DataType<?> source, DataType<?> result) throws TransformerException;
133 
134     Collection<Service> lookupServices(String model);
135 
136     Collection<Service> lookupServices();
137 
138     Collection<FlowConstruct> lookupFlowConstructs();
139 
140     Model lookupModel(String name);
141 
142     Model lookupSystemModel();
143 
144     Agent lookupAgent(String agentName);
145 
146     /**
147      * @deprecated Use lookupModel() instead
148      */
149     @Deprecated
150     Collection<Model> getModels();
151 
152     /**
153      * @deprecated Use lookupConnector() instead
154      */
155     @Deprecated
156     Collection<Connector> getConnectors();
157 
158     /**
159      * @deprecated Use {@link org.mule.api.endpoint.EndpointFactory} for creation/lookup of individual endpoints instead
160      */
161     @Deprecated
162     Collection<ImmutableEndpoint> getEndpoints();
163 
164     /**
165      * @deprecated Use lookupAgent() instead
166      */
167     @Deprecated
168     Collection<Agent> getAgents();
169 
170     /**
171      * @deprecated Use lookupTransformer() instead
172      */
173     @Deprecated
174     Collection<Transformer> getTransformers();
175 
176     // /////////////////////////////////////////////////////////////////////////
177     // Registration methods
178     // /////////////////////////////////////////////////////////////////////////
179 
180     void registerConnector(Connector connector) throws MuleException;
181 
182     void unregisterConnector(String connectorName) throws MuleException;
183 
184     //TODO MULE-2494
185     void registerEndpoint(ImmutableEndpoint endpoint) throws MuleException;
186 
187     //TODO MULE-2494
188     void unregisterEndpoint(String endpointName) throws MuleException;
189 
190     public void registerEndpointBuilder(String name, EndpointBuilder builder) throws MuleException;
191 
192     void registerTransformer(Transformer transformer) throws MuleException;
193 
194     void unregisterTransformer(String transformerName) throws MuleException;
195 
196     void registerService(Service service) throws MuleException;
197 
198     void unregisterService(String serviceName) throws MuleException;
199 
200     void registerFlowConstruct(FlowConstruct flowConstruct) throws MuleException;
201 
202     void unregisterFlowConstruct(String flowConstructName) throws MuleException;
203 
204     void registerModel(Model model) throws MuleException;
205 
206     void unregisterModel(String modelName) throws MuleException;
207 
208     void registerAgent(Agent agent) throws MuleException;
209 
210     void unregisterAgent(String agentName) throws MuleException;
211 
212     /**
213      * Will execute any processors on an object and fire any lifecycle methods according to the current lifecycle without actually
214      * registering the object in the registry.  This is useful for prototype objects that are created per request and would
215      * clutter the registry with single use objects.  Not that this will only be applied to Mule registies.  Thrid party registries
216      * such as Guice support wiring, but you need to get a reference to the container/context to call the method.  This is so that
217      * wiring mechanisms dont trip over each other.
218      *
219      * @param object the object to process
220      * @return the same object with any processors and lifecycle methods called
221      * @throws org.mule.api.MuleException if the registry fails to perform the lifecycle change or process object processors for the object.
222      */
223     Object applyProcessorsAndLifecycle(Object object) throws MuleException;
224 
225     /**
226      * Will execute any processors on an object without actually registering the object in the registry.  This is useful for prototype objects that are created per request and would
227      * clutter the registry with single use objects.  Not that this will only be applied to Mule registies.  Thrid party registries
228      * such as Guice support wiring, but you need to get a reference to the container/context to call the method.  This is so that
229      * wiring mechanisms dont trip over each other.
230      *
231      * @param object the object to process
232      * @return the same object with any processors called
233      * @throws org.mule.api.MuleException if the registry fails to process object processors for the object.
234      */
235     Object applyProcessors(Object object) throws MuleException;
236 
237     /**
238      * Will execute any processors on an object without actually registering the object in the registry.  This is useful for prototype objects that are created per request and would
239      * clutter the registry with single use objects.  Not that this will only be applied to Mule registies.  Thrid party registries
240      * such as Guice support wiring, but you need to get a reference to the container/context to call the method.  This is so that
241      * wiring mechanisms dont trip over each other.
242      *
243      * @param object the object to process
244      * @param flags {@link org.mule.api.registry.MuleRegistry} flags which control which injectors will be applied
245      * @return the same object with any processors called
246      * @throws org.mule.api.MuleException if the registry fails to process object processors for the object.
247      *
248      * @since 3.0
249      */
250     Object applyProcessors(Object object, int flags) throws MuleException;
251 
252     /**
253      * Will execute any lifecycle phases on an object without actually registering the object in the registry.  This is useful for prototype objects that are created per request and would
254      * clutter the registry with single use objects. The lifecycle applied is the lifecycle of the MuleContext. If multiple phases have
255      * been completed i.e. init and start, each phase will be executed on the object in order.
256      *
257      * @param object the object to apply the current lifecycle state to
258      * @return the same object with any lifecycle methods called
259      * @throws org.mule.api.MuleException if the registry fails to execute a lifecycle method.
260      */
261     Object applyLifecycle(Object object) throws MuleException;
262 
263     Object applyLifecycle(Object object, String phase) throws MuleException;
264 
265     // /////////////////////////////////////////////////////////////////////////
266     // Creation methods
267     // /////////////////////////////////////////////////////////////////////////
268 
269     // TODO These methods are a mess (they blur lookup with creation, uris with names). Need to clean this up.
270 
271     ServiceDescriptor lookupServiceDescriptor(ServiceType type, String name, Properties overrides)
272             throws ServiceException;
273 }