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 default domain on the MBean server
106     *
107     * @param domain the domain
108     */
109    void setMBeanServerDefaultDomain(String domain);
110
111    /**
112     * Gets the default domain on the MBean server
113     *
114     * @return the domain
115     */
116    String getMBeanServerDefaultDomain();
117
118    /**
119     * Sets the object domain name
120     *
121     * @param domainName the object domain name
122     */
123    void setMBeanObjectDomainName(String domainName);
124
125    /**
126     * Whether to use the platform MBean Server.
127     *
128     * @param usePlatformMBeanServer <tt>true</tt> to use platform MBean server
129     */
130    void setUsePlatformMBeanServer(Boolean usePlatformMBeanServer);
131
132    /**
133     * Whether to use the platform MBean Server.
134     *
135     * @return <tt>true</tt> if platform MBean server is to be used
136     */
137    Boolean getUsePlatformMBeanServer();
138
139    /**
140     * Whether to only register processors which has a custom id assigned.
141     * <p/>
142     * This allows you to filter unwanted processors.
143     *
144     * @return <tt>true</tt> if only processors with custom id is registered
145     */
146    Boolean getOnlyRegisterProcessorWithCustomId();
147
148    /**
149     * Whether to only register processors which has a custom id assigned.
150     * <p/>
151     * This allows you to filter unwanted processors.
152     *
153     * @param onlyRegisterProcessorWithCustomId <tt>true</tt> to only register if custom id has been assigned
154     */
155    void setOnlyRegisterProcessorWithCustomId(Boolean onlyRegisterProcessorWithCustomId);
156
157    /**
158     * Whether to always register mbeans.
159     * <p/>
160     * This option is default <tt>false</tt>.
161     * <p/>
162     * <b>Important:</b> If this option is enabled then any service is registered as mbean. When using
163     * dynamic EIP patterns using unique endpoint urls, you may create excessive mbeans in the registry.
164     * This could lead to degraded performance as memory consumption will rise due the rising number
165     * of mbeans.
166     *
167     * @return <tt>true</tt> if always registering
168     */
169    Boolean getRegisterAlways();
170
171    /**
172     * Whether to always register mbeans.
173     * <p/>
174     * This option is default <tt>false</tt>.
175     * <p/>
176     * <b>Important:</b> If this option is enabled then any service is registered as mbean. When using
177     * dynamic EIP patterns using unique endpoint urls, you may create excessive mbeans in the registry.
178     * This could lead to degraded performance as memory consumption will rise due the rising number
179     * of mbeans.
180     *
181     * @param registerAlways <tt>true</tt> to always register
182     */
183    void setRegisterAlways(Boolean registerAlways);
184
185    /**
186     * Whether to register mbeans when starting a new route
187     * <p/>
188     * This option is default <tt>true</tt>.
189     *
190     * @return <tt>true</tt> to register when starting a new route
191     */
192    Boolean getRegisterNewRoutes();
193
194    /**
195     * Whether to register mbeans when starting a new route
196     * <p/>
197     * This option is default <tt>true</tt>.
198     *
199     * @param registerNewRoutes <tt>true</tt> to register when starting a new route
200     */
201    void setRegisterNewRoutes(Boolean registerNewRoutes);
202
203    /**
204     * Whether to remove detected sensitive information (such as passwords) from MBean names and attributes.
205     * <p/>
206     * This option is default <tt>false</tt>.
207     */
208    Boolean getMask();
209
210    /**
211     * Whether to remove detected sensitive information (such as passwords) from MBean names and attributes.
212     * <p/>
213     * This option is default <tt>false</tt>.
214     */
215    void setMask(Boolean sanitize);
216
217    /**
218     * Gets whether host name is included in MBean names.
219     *
220     * @return <tt>true</tt> if included
221     */
222    Boolean getIncludeHostName();
223
224    /**
225     * Sets whether to include host name in the {@link ManagementNamingStrategy}.
226     * <p/>
227     * By default this is turned off from Camel 2.13 onwards, but this option
228     * can be set to <tt>true</tt> to include the hostname as Camel 2.12 or
229     * older releases does.
230     *
231     * @param includeHostName <tt>true</tt> to include host name in the MBean names.
232     */
233    void setIncludeHostName(Boolean includeHostName);
234
235    /**
236     * The naming pattern for creating the CamelContext management name.
237     * <p/>
238     * The default pattern is <tt>#name#</tt>
239     */
240    String getManagementNamePattern();
241
242    /**
243     * The naming pattern for creating the CamelContext management name.
244     * <p/>
245     * The default pattern is <tt>#name#</tt>
246     */
247    void setManagementNamePattern(String managementNamePattern);
248
249    /**
250     * Sets whether load statistics is enabled (gathers load statistics using a background thread per CamelContext).
251     * <p/>
252     * The default value is <tt>false</tt>
253     *
254     * @param flag <tt>true</tt> to enable load statistics
255     */
256    void setLoadStatisticsEnabled(Boolean flag);
257
258    /**
259     * Gets whether load statistics is enabled
260     *
261     * @return <tt>true</tt> if enabled
262     */
263    Boolean getLoadStatisticsEnabled();
264
265    /**
266     * Sets whether endpoint runtime statistics is enabled (gathers runtime usage of each incoming and outgoing endpoints).
267     * <p/>
268     * The default value is <tt>false</tt>
269     *
270     * @param flag <tt>true</tt> to enable endpoint runtime statistics
271     */
272    void setEndpointRuntimeStatisticsEnabled(Boolean flag);
273
274    /**
275     * Gets whether endpoint runtime statistics is enabled
276     *
277     * @return <tt>true</tt> if enabled
278     */
279    Boolean getEndpointRuntimeStatisticsEnabled();
280
281    /**
282     * Sets the statistics level
283     * <p/>
284     * Default is {@link org.apache.camel.ManagementStatisticsLevel#Default}
285     * <p/>
286     * The level can be set to <tt>Extended</tt> to gather additional information
287     *
288     * @param level the new level
289     */
290    void setStatisticsLevel(ManagementStatisticsLevel level);
291
292    /**
293     * Gets the statistics level
294     *
295     * @return the level
296     */
297    ManagementStatisticsLevel getStatisticsLevel();
298    
299    /**
300     * Gets whether host IP Address to be used instead of host name.
301     *
302     * @return <tt>true</tt> if included
303     */
304    Boolean getUseHostIPAddress();
305
306    /**
307     * Sets whether to use host IP Address 
308     * @param useHostIPAddress <tt>true</tt> to use IP Address.
309     */
310    void setUseHostIPAddress(Boolean useHostIPAddress);
311
312}