View Javadoc

1   /*
2    * $Id: MuleRegistry.java 20385 2010-11-29 20:25:26Z dfeist $
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       * @return
79       */
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      List<Transformer> lookupTransformers(Class input, Class output);
98  
99      /**
100      * This method will return a list of {@link org.mule.api.transformer.Transformer} objects that accept the given
101      * input and return the given output type of object
102      *
103      * @param source The  desired input type for the transformer
104      * @param result the desired output type for the transformer
105      * @return a list of matching transformers. If there were no matchers an empty list is returned.
106      * @since 3.0.0
107      */
108     List<Transformer> lookupTransformers(DataType source, DataType result);
109 
110     /**
111      * Will find a transformer that is the closest match to the desired input and output.
112      *
113      * @param input  The  desiered input type for the transformer
114      * @param output the desired output type for the transformer
115      * @return A transformer that exactly matches or the will accept the input and output parameters
116      * @throws TransformerException will be thrown if there is more than one match
117      * @deprecated use {@link #lookupTransformer(org.mule.api.transformer.DataType, org.mule.api.transformer.DataType)} instead
118      */
119     Transformer lookupTransformer(Class input, Class output) throws TransformerException;
120 
121     /**
122      * Will find a transformer that is the closest match to the desired input and output.
123      *
124      * @param source The  desiered input type for the transformer
125      * @param result the desired output type for the transformer
126      * @return A transformer that exactly matches or the will accept the input and output parameters
127      * @throws TransformerException will be thrown if there is more than one match
128      * @since 3.0.0
129      */
130     Transformer lookupTransformer(DataType source, DataType result) throws TransformerException;
131 
132     Collection<Service> lookupServices(String model);
133 
134     Collection<Service> lookupServices();
135 
136     Collection<FlowConstruct> lookupFlowConstructs();
137     
138     Model lookupModel(String name);
139 
140     Model lookupSystemModel();
141 
142     Agent lookupAgent(String agentName);
143 
144     /**
145      * @deprecated Use lookupModel() instead
146      */
147     Collection<Model> getModels();
148 
149     /**
150      * @deprecated Use lookupConnector() instead
151      */
152     Collection<Connector> getConnectors();
153 
154     /**
155      * @deprecated Use {@link org.mule.api.endpoint.EndpointFactory} for creation/lookup of individual endpoints instead
156      */
157     Collection<ImmutableEndpoint> getEndpoints();
158 
159     /**
160      * @deprecated Use lookupAgent() instead
161      */
162     Collection<Agent> getAgents();
163 
164     /**
165      * @deprecated Use lookupTransformer() instead
166      */
167     Collection<Transformer> getTransformers();
168 
169     // /////////////////////////////////////////////////////////////////////////
170     // Registration methods
171     // /////////////////////////////////////////////////////////////////////////
172 
173     void registerConnector(Connector connector) throws MuleException;
174 
175     void unregisterConnector(String connectorName) throws MuleException;
176 
177     //TODO MULE-2494
178     void registerEndpoint(ImmutableEndpoint endpoint) throws MuleException;
179 
180     //TODO MULE-2494
181     void unregisterEndpoint(String endpointName) throws MuleException;
182 
183     public void registerEndpointBuilder(String name, EndpointBuilder builder) throws MuleException;
184 
185     void registerTransformer(Transformer transformer) throws MuleException;
186 
187     void unregisterTransformer(String transformerName) throws MuleException;
188 
189     void registerService(Service service) throws MuleException;
190 
191     void unregisterService(String serviceName) throws MuleException;
192 
193     void registerFlowConstruct(FlowConstruct flowConstruct) throws MuleException;
194 
195     void unregisterFlowConstruct(String flowConstructName) throws MuleException;
196     
197     void registerModel(Model model) throws MuleException;
198 
199     void unregisterModel(String modelName) throws MuleException;
200 
201     void registerAgent(Agent agent) throws MuleException;
202 
203     void unregisterAgent(String agentName) throws MuleException;
204 
205     /**
206      * Will execute any processors on an object and fire any lifecycle methods according to the current lifecycle without actually
207      * registering the object in the registry.  This is useful for prototype objects that are created per request and would
208      * clutter the registry with single use objects.  Not that this will only be applied to Mule registies.  Thrid party registries
209      * such as Guice support wiring, but you need to get a reference to the container/context to call the method.  This is so that
210      * wiring mechanisms dont trip over each other.
211      *
212      * @param object the object to process
213      * @return the same object with any processors and lifecycle methods called
214      * @throws org.mule.api.MuleException if the registry fails to perform the lifecycle change or process object processors for the object.
215      */
216     Object applyProcessorsAndLifecycle(Object object) throws MuleException;
217 
218     /**
219      * 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
220      * clutter the registry with single use objects.  Not that this will only be applied to Mule registies.  Thrid party registries
221      * such as Guice support wiring, but you need to get a reference to the container/context to call the method.  This is so that
222      * wiring mechanisms dont trip over each other.
223      *
224      * @param object the object to process
225      * @return the same object with any processors called
226      * @throws org.mule.api.MuleException if the registry fails to process object processors for the object.
227      */
228     Object applyProcessors(Object object) throws MuleException;
229 
230     /**
231      * 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
232      * clutter the registry with single use objects.  Not that this will only be applied to Mule registies.  Thrid party registries
233      * such as Guice support wiring, but you need to get a reference to the container/context to call the method.  This is so that
234      * wiring mechanisms dont trip over each other.
235      *
236      * @param object the object to process
237      * @param flags {@link org.mule.api.registry.MuleRegistry} flags which control which injectors will be applied
238      * @return the same object with any processors called
239      * @throws org.mule.api.MuleException if the registry fails to process object processors for the object.
240      *
241      * @since 3.0
242      */
243     Object applyProcessors(Object object, int flags) throws MuleException;
244 
245     /**
246      * 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
247      * clutter the registry with single use objects. The lifecycle applied is the lifecycle of the MuleContext. If multiple phases have
248      * been completed i.e. init and start, each phase will be executed on the object in order.
249      *
250      * @param object the object to apply the current lifecycle state to
251      * @return the same object with any lifecycle methods called
252      * @throws org.mule.api.MuleException if the registry fails to execute a lifecycle method.
253 b     */
254     Object applyLifecycle(Object object) throws MuleException;
255 
256     Object applyLifecycle(Object object, String phase) throws MuleException;
257 
258     // /////////////////////////////////////////////////////////////////////////
259     // Creation methods
260     // /////////////////////////////////////////////////////////////////////////
261 
262     // TODO These methods are a mess (they blur lookup with creation, uris with names). Need to clean this up.
263 
264     ServiceDescriptor lookupServiceDescriptor(ServiceType type, String name, Properties overrides)
265             throws ServiceException;
266 }