View Javadoc

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