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.Service;
024
025/**
026 * Camel JMX service agent
027 */
028public interface ManagementAgent extends Service {
029
030    /**
031     * Registers object with management infrastructure with a specific name. Object must be annotated or 
032     * implement standard MBean interface.
033     *
034     * @param obj  the object to register
035     * @param name the name
036     * @throws JMException is thrown if the registration failed
037     */
038    void register(Object obj, ObjectName name) throws JMException;
039    
040    /**
041     * Registers object with management infrastructure with a specific name. Object must be annotated or 
042     * implement standard MBean interface.
043     *
044     * @param obj  the object to register
045     * @param name the name
046     * @param forceRegistration if set to <tt>true</tt>, then object will be registered despite
047     * existing object is already registered with the name.
048     * @throws JMException is thrown if the registration failed
049     */
050    void register(Object obj, ObjectName name, boolean forceRegistration) throws JMException;
051    
052    /**
053     * Unregisters object based upon registered name
054     *
055     * @param name the name
056     * @throws JMException is thrown if the unregistration failed
057     */
058    void unregister(ObjectName name) throws JMException;
059
060    /**
061     * Is the given object registered
062     *
063     * @param name the name
064     * @return <tt>true</tt> if registered
065     */
066    boolean isRegistered(ObjectName name);
067
068    /**
069     * Get the MBeanServer which hosts managed objects.
070     * <p/>
071     * <b>Notice:</b> If the JMXEnabled configuration is not set to <tt>true</tt>,
072     * this method will return <tt>null</tt>.
073     * 
074     * @return the MBeanServer
075     */
076    MBeanServer getMBeanServer();
077
078    /**
079     * Sets a custom mbean server to use
080     *
081     * @param mbeanServer the custom mbean server
082     */
083    void setMBeanServer(MBeanServer mbeanServer);
084
085    /**
086     * Get domain name for Camel MBeans.
087     * <p/>
088     * <b>Notice:</b> That this can be different that the default domain name of the MBean Server.
089     * 
090     * @return domain name
091     */
092    String getMBeanObjectDomainName();
093
094    /**
095     * Sets the port used by {@link java.rmi.registry.LocateRegistry}.
096     *
097     * @param port the port
098     */
099    void setRegistryPort(Integer port);
100
101    /**
102     * Gets the port used by {@link java.rmi.registry.LocateRegistry}.
103     *
104     * @return the port
105     */
106    Integer getRegistryPort();
107
108    /**
109     * Sets the port clients must use to connect
110     *
111     * @param port the port
112     */
113    void setConnectorPort(Integer port);
114
115    /**
116     * Gets the port clients must use to connect
117     *
118     * @return the port
119     */
120    Integer getConnectorPort();
121
122    /**
123     * Sets the default domain on the MBean server
124     *
125     * @param domain the domain
126     */
127    void setMBeanServerDefaultDomain(String domain);
128
129    /**
130     * Gets the default domain on the MBean server
131     *
132     * @return the domain
133     */
134    String getMBeanServerDefaultDomain();
135
136    /**
137     * Sets the object domain name
138     *
139     * @param domainName the object domain name
140     */
141    void setMBeanObjectDomainName(String domainName);
142
143    /**
144     * Sets the service url
145     *
146     * @param url the service url
147     */
148    void setServiceUrlPath(String url);
149
150    /**
151     * Gets the service url
152     *
153     * @return the url
154     */
155    String getServiceUrlPath();
156
157    /**
158     * Whether connector should be created, allowing clients to connect remotely
159     *
160     * @param createConnector <tt>true</tt> to create connector
161     */
162    void setCreateConnector(Boolean createConnector);
163
164    /**
165     * Whether connector is created, allowing clients to connect remotely
166     *
167     * @return <tt>true</tt> if connector is created
168     */
169    Boolean getCreateConnector();
170
171    /**
172     * Whether to use the platform MBean Server.
173     *
174     * @param usePlatformMBeanServer <tt>true</tt> to use platform MBean server
175     */
176    void setUsePlatformMBeanServer(Boolean usePlatformMBeanServer);
177
178    /**
179     * Whether to use the platform MBean Server.
180     *
181     * @return <tt>true</tt> if platform MBean server is to be used
182     */
183    Boolean getUsePlatformMBeanServer();
184
185    /**
186     * Whether to only register processors which has a custom id assigned.
187     * <p/>
188     * This allows you to filter unwanted processors.
189     *
190     * @return <tt>true</tt> if only processors with custom id is registered
191     */
192    Boolean getOnlyRegisterProcessorWithCustomId();
193
194    /**
195     * Whether to only register processors which has a custom id assigned.
196     * <p/>
197     * This allows you to filter unwanted processors.
198     *
199     * @param onlyRegisterProcessorWithCustomId <tt>true</tt> to only register if custom id has been assigned
200     */
201    void setOnlyRegisterProcessorWithCustomId(Boolean onlyRegisterProcessorWithCustomId);
202
203    /**
204     * Whether to always register mbeans.
205     * <p/>
206     * This option is default <tt>false</tt>.
207     * <p/>
208     * <b>Important:</b> If this option is enabled then any service is registered as mbean. When using
209     * dynamic EIP patterns using unique endpoint urls, you may create excessive mbeans in the registry.
210     * This could lead to degraded performance as memory consumption will rise due the rising number
211     * of mbeans.
212     *
213     * @return <tt>true</tt> if always registering
214     */
215    Boolean getRegisterAlways();
216
217    /**
218     * Whether to always register mbeans.
219     * <p/>
220     * This option is default <tt>false</tt>.
221     * <p/>
222     * <b>Important:</b> If this option is enabled then any service is registered as mbean. When using
223     * dynamic EIP patterns using unique endpoint urls, you may create excessive mbeans in the registry.
224     * This could lead to degraded performance as memory consumption will rise due the rising number
225     * of mbeans.
226     *
227     * @param registerAlways <tt>true</tt> to always register
228     */
229    void setRegisterAlways(Boolean registerAlways);
230
231    /**
232     * Whether to register mbeans when starting a new route
233     * <p/>
234     * This option is default <tt>true</tt>.
235     *
236     * @return <tt>true</tt> to register when starting a new route
237     */
238    Boolean getRegisterNewRoutes();
239
240    /**
241     * Whether to register mbeans when starting a new route
242     * <p/>
243     * This option is default <tt>true</tt>.
244     *
245     * @param registerNewRoutes <tt>true</tt> to register when starting a new route
246     */
247    void setRegisterNewRoutes(Boolean registerNewRoutes);
248
249    /**
250     * Whether to remove detected sensitive information (such as passwords) from MBean names and attributes.
251     * <p/>
252     * This option is default <tt>false</tt>.
253     */
254    Boolean getMask();
255
256    /**
257     * Whether to remove detected sensitive information (such as passwords) from MBean names and attributes.
258     * <p/>
259     * This option is default <tt>false</tt>.
260     */
261    void setMask(Boolean sanitize);
262
263    /**
264     * Gets whether host name is included in MBean names.
265     *
266     * @return <tt>true</tt> if included
267     */
268    Boolean getIncludeHostName();
269
270    /**
271     * Sets whether to include host name in the {@link ManagementNamingStrategy}.
272     * <p/>
273     * By default this is turned off from Camel 2.13 onwards, but this option
274     * can be set to <tt>true</tt> to include the hostname as Camel 2.12 or
275     * older releases does.
276     *
277     * @param includeHostName <tt>true</tt> to include host name in the MBean names.
278     */
279    void setIncludeHostName(Boolean includeHostName);
280
281}