001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.camel.spi;
018
019import javax.management.JMException;
020import javax.management.MBeanServer;
021import javax.management.ObjectName;
022
023import org.apache.camel.ManagementStatisticsLevel;
024import org.apache.camel.Service;
025
026/**
027 * Camel JMX service agent
028 */
029public interface ManagementAgent extends Service {
030
031    /**
032     * Registers object with management infrastructure with a specific name. Object must be annotated or 
033     * implement standard MBean interface.
034     *
035     * @param obj  the object to register
036     * @param name the name
037     * @throws JMException is thrown if the registration failed
038     */
039    void register(Object obj, ObjectName name) throws JMException;
040    
041    /**
042     * Registers object with management infrastructure with a specific name. Object must be annotated or 
043     * implement standard MBean interface.
044     *
045     * @param obj  the object to register
046     * @param name the name
047     * @param forceRegistration if set to <tt>true</tt>, then object will be registered despite
048     * existing object is already registered with the name.
049     * @throws JMException is thrown if the registration failed
050     */
051    void register(Object obj, ObjectName name, boolean forceRegistration) throws JMException;
052    
053    /**
054     * Unregisters object based upon registered name
055     *
056     * @param name the name
057     * @throws JMException is thrown if the unregistration failed
058     */
059    void unregister(ObjectName name) throws JMException;
060
061    /**
062     * Is the given object registered
063     *
064     * @param name the name
065     * @return <tt>true</tt> if registered
066     */
067    boolean isRegistered(ObjectName name);
068
069    /**
070     * Creates a new proxy client
071     *
072     * @param name   the mbean name
073     * @param mbean  the client interface, such as from the {@link org.apache.camel.api.management.mbean} package.
074     * @return the client or <tt>null</tt> if mbean does not exists
075     */
076    <T> T newProxyClient(ObjectName name, Class<T> mbean);
077
078    /**
079     * Get the MBeanServer which hosts managed objects.
080     * <p/>
081     * <b>Notice:</b> If the JMXEnabled configuration is not set to <tt>true</tt>,
082     * this method will return <tt>null</tt>.
083     * 
084     * @return the MBeanServer
085     */
086    MBeanServer getMBeanServer();
087
088    /**
089     * Sets a custom mbean server to use
090     *
091     * @param mbeanServer the custom mbean server
092     */
093    void setMBeanServer(MBeanServer mbeanServer);
094
095    /**
096     * Get domain name for Camel MBeans.
097     * <p/>
098     * <b>Notice:</b> That this can be different that the default domain name of the MBean Server.
099     * 
100     * @return domain name
101     */
102    String getMBeanObjectDomainName();
103
104    /**
105     * Sets the port used by {@link java.rmi.registry.LocateRegistry}.
106     *
107     * @param port the port
108     */
109    void setRegistryPort(Integer port);
110
111    /**
112     * Gets the port used by {@link java.rmi.registry.LocateRegistry}.
113     *
114     * @return the port
115     */
116    Integer getRegistryPort();
117
118    /**
119     * Sets the port clients must use to connect
120     *
121     * @param port the port
122     */
123    void setConnectorPort(Integer port);
124
125    /**
126     * Gets the port clients must use to connect
127     *
128     * @return the port
129     */
130    Integer getConnectorPort();
131
132    /**
133     * Sets the default domain on the MBean server
134     *
135     * @param domain the domain
136     */
137    void setMBeanServerDefaultDomain(String domain);
138
139    /**
140     * Gets the default domain on the MBean server
141     *
142     * @return the domain
143     */
144    String getMBeanServerDefaultDomain();
145
146    /**
147     * Sets the object domain name
148     *
149     * @param domainName the object domain name
150     */
151    void setMBeanObjectDomainName(String domainName);
152
153    /**
154     * Sets the service url
155     *
156     * @param url the service url
157     */
158    void setServiceUrlPath(String url);
159
160    /**
161     * Gets the service url
162     *
163     * @return the url
164     */
165    String getServiceUrlPath();
166
167    /**
168     * Whether connector should be created, allowing clients to connect remotely
169     *
170     * @param createConnector <tt>true</tt> to create connector
171     */
172    void setCreateConnector(Boolean createConnector);
173
174    /**
175     * Whether connector is created, allowing clients to connect remotely
176     *
177     * @return <tt>true</tt> if connector is created
178     */
179    Boolean getCreateConnector();
180
181    /**
182     * Whether to use the platform MBean Server.
183     *
184     * @param usePlatformMBeanServer <tt>true</tt> to use platform MBean server
185     */
186    void setUsePlatformMBeanServer(Boolean usePlatformMBeanServer);
187
188    /**
189     * Whether to use the platform MBean Server.
190     *
191     * @return <tt>true</tt> if platform MBean server is to be used
192     */
193    Boolean getUsePlatformMBeanServer();
194
195    /**
196     * Whether to only register processors which has a custom id assigned.
197     * <p/>
198     * This allows you to filter unwanted processors.
199     *
200     * @return <tt>true</tt> if only processors with custom id is registered
201     */
202    Boolean getOnlyRegisterProcessorWithCustomId();
203
204    /**
205     * Whether to only register processors which has a custom id assigned.
206     * <p/>
207     * This allows you to filter unwanted processors.
208     *
209     * @param onlyRegisterProcessorWithCustomId <tt>true</tt> to only register if custom id has been assigned
210     */
211    void setOnlyRegisterProcessorWithCustomId(Boolean onlyRegisterProcessorWithCustomId);
212
213    /**
214     * Whether to always register mbeans.
215     * <p/>
216     * This option is default <tt>false</tt>.
217     * <p/>
218     * <b>Important:</b> If this option is enabled then any service is registered as mbean. When using
219     * dynamic EIP patterns using unique endpoint urls, you may create excessive mbeans in the registry.
220     * This could lead to degraded performance as memory consumption will rise due the rising number
221     * of mbeans.
222     *
223     * @return <tt>true</tt> if always registering
224     */
225    Boolean getRegisterAlways();
226
227    /**
228     * Whether to always register mbeans.
229     * <p/>
230     * This option is default <tt>false</tt>.
231     * <p/>
232     * <b>Important:</b> If this option is enabled then any service is registered as mbean. When using
233     * dynamic EIP patterns using unique endpoint urls, you may create excessive mbeans in the registry.
234     * This could lead to degraded performance as memory consumption will rise due the rising number
235     * of mbeans.
236     *
237     * @param registerAlways <tt>true</tt> to always register
238     */
239    void setRegisterAlways(Boolean registerAlways);
240
241    /**
242     * Whether to register mbeans when starting a new route
243     * <p/>
244     * This option is default <tt>true</tt>.
245     *
246     * @return <tt>true</tt> to register when starting a new route
247     */
248    Boolean getRegisterNewRoutes();
249
250    /**
251     * Whether to register mbeans when starting a new route
252     * <p/>
253     * This option is default <tt>true</tt>.
254     *
255     * @param registerNewRoutes <tt>true</tt> to register when starting a new route
256     */
257    void setRegisterNewRoutes(Boolean registerNewRoutes);
258
259    /**
260     * Whether to remove detected sensitive information (such as passwords) from MBean names and attributes.
261     * <p/>
262     * This option is default <tt>false</tt>.
263     */
264    Boolean getMask();
265
266    /**
267     * Whether to remove detected sensitive information (such as passwords) from MBean names and attributes.
268     * <p/>
269     * This option is default <tt>false</tt>.
270     */
271    void setMask(Boolean sanitize);
272
273    /**
274     * Gets whether host name is included in MBean names.
275     *
276     * @return <tt>true</tt> if included
277     */
278    Boolean getIncludeHostName();
279
280    /**
281     * Sets whether to include host name in the {@link ManagementNamingStrategy}.
282     * <p/>
283     * By default this is turned off from Camel 2.13 onwards, but this option
284     * can be set to <tt>true</tt> to include the hostname as Camel 2.12 or
285     * older releases does.
286     *
287     * @param includeHostName <tt>true</tt> to include host name in the MBean names.
288     */
289    void setIncludeHostName(Boolean includeHostName);
290
291    /**
292     * The naming pattern for creating the CamelContext management name.
293     * <p/>
294     * The default pattern is <tt>#name#</tt>
295     */
296    String getManagementNamePattern();
297
298    /**
299     * The naming pattern for creating the CamelContext management name.
300     * <p/>
301     * The default pattern is <tt>#name#</tt>
302     */
303    void setManagementNamePattern(String managementNamePattern);
304
305    /**
306     * Sets whether load statistics is enabled (gathers load statistics using a background thread per CamelContext).
307     * <p/>
308     * The default value is <tt>false</tt>
309     *
310     * @param flag <tt>true</tt> to enable load statistics
311     */
312    void setLoadStatisticsEnabled(Boolean flag);
313
314    /**
315     * Gets whether load statistics is enabled
316     *
317     * @return <tt>true</tt> if enabled
318     */
319    Boolean getLoadStatisticsEnabled();
320
321    /**
322     * Sets whether endpoint runtime statistics is enabled (gathers runtime usage of each incoming and outgoing endpoints).
323     * <p/>
324     * The default value is <tt>false</tt>
325     *
326     * @param flag <tt>true</tt> to enable endpoint runtime statistics
327     */
328    void setEndpointRuntimeStatisticsEnabled(Boolean flag);
329
330    /**
331     * Gets whether endpoint runtime statistics is enabled
332     *
333     * @return <tt>true</tt> if enabled
334     */
335    Boolean getEndpointRuntimeStatisticsEnabled();
336
337    /**
338     * Sets the statistics level
339     * <p/>
340     * Default is {@link org.apache.camel.ManagementStatisticsLevel#Default}
341     * <p/>
342     * The level can be set to <tt>Extended</tt> to gather additional information
343     *
344     * @param level the new level
345     */
346    void setStatisticsLevel(ManagementStatisticsLevel level);
347
348    /**
349     * Gets the statistics level
350     *
351     * @return the level
352     */
353    ManagementStatisticsLevel getStatisticsLevel();
354    
355    /**
356     * Gets whether host IP Address to be used instead of host name.
357     *
358     * @return <tt>true</tt> if included
359     */
360    Boolean getUseHostIPAddress();
361
362    /**
363     * Sets whether to use host IP Address 
364     * @param useHostIPAddress <tt>true</tt> to use IP Address.
365     */
366    void setUseHostIPAddress(Boolean useHostIPAddress);
367
368}