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