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 java.util.EventObject;
020import java.util.List;
021
022import org.apache.camel.ManagementStatisticsLevel;
023import org.apache.camel.Service;
024import org.apache.camel.model.ProcessorDefinition;
025
026/**
027 * Strategy for management.
028 * <p/>
029 * This is totally pluggable allowing to use a custom or 3rd party management implementation with Camel.
030 *
031 * @see org.apache.camel.spi.EventNotifier
032 * @see org.apache.camel.spi.EventFactory
033 * @see org.apache.camel.spi.ManagementNamingStrategy
034 * @see org.apache.camel.spi.ManagementAgent
035 * @version 
036 */
037public interface ManagementStrategy extends Service {
038
039    /**
040     * Adds a managed object allowing the ManagementStrategy implementation to record or expose
041     * the object as it sees fit.
042     *
043     * @param managedObject the managed object
044     * @throws Exception can be thrown if the object could not be added
045     */
046    void manageObject(Object managedObject) throws Exception;
047
048    /**
049     * Adds a managed object allowing the ManagementStrategy implementation
050     * to record or expose the object as it sees fit.
051     *
052     * @param managedObject the managed object
053     * @param preferredName representing the preferred name, maybe a String, or a JMX ObjectName
054     * @throws Exception can be thrown if the object could not be added
055     */
056    void manageNamedObject(Object managedObject, Object preferredName) throws Exception;
057
058    /**
059     * Construct an object name, where either the object to be managed and/or
060     * a custom name component are provided
061     *
062     * @param managedObject the object to be managed
063     * @param customName a custom name component
064     * @param nameType the name type required
065     * @return an object name of the required type if supported, otherwise <tt>null</tt>
066     * @throws Exception can be thrown if the object name could not be created
067     */
068    <T> T getManagedObjectName(Object managedObject, String customName, Class<T> nameType) throws Exception;
069
070    /**
071     * Removes the managed object.
072     *
073     * @param managedObject the managed object
074     * @throws Exception can be thrown if the object could not be removed
075     */
076    void unmanageObject(Object managedObject) throws Exception;
077
078    /**
079     * Removes a managed object by name.
080     *
081     * @param name an object name previously created by this strategy.
082     * @throws Exception can be thrown if the object could not be removed
083     */
084    void unmanageNamedObject(Object name) throws Exception;
085
086    /**
087     * Determines if an object or name is managed.
088     *
089     * @param managedObject the object to consider
090     * @param name the name to consider
091     * @return <tt>true</tt> if the given object or name is managed
092     */
093    boolean isManaged(Object managedObject, Object name);
094
095    /**
096     * Management events provide a single model for capturing information about execution points in the
097     * application code. Management strategy implementations decide if and where to record these events.
098     * Applications communicate events to management strategy implementations via the notify(EventObject)
099     * method.
100     *
101     * @param event the event
102     * @throws Exception can be thrown if the notification failed
103     */
104    void notify(EventObject event) throws Exception;
105
106    /**
107     * Gets the event notifiers.
108     *
109     * @return event notifiers
110     */
111    List<EventNotifier> getEventNotifiers();
112
113    /**
114     * Sets the list of event notifier to use.
115     *
116     * @param eventNotifier list of event notifiers
117     */
118    void setEventNotifiers(List<EventNotifier> eventNotifier);
119
120    /**
121     * Adds the event notifier to use.
122     * <p/>
123     * Ensure the event notifier has been started if its a {@link Service}, as otherwise
124     * it would not be used.
125     *
126     * @param eventNotifier event notifier
127     */
128    void addEventNotifier(EventNotifier eventNotifier);
129
130    /**
131     * Removes the event notifier
132     *
133     * @param eventNotifier event notifier to remove
134     * @return <tt>true</tt> if removed, <tt>false</tt> if already removed
135     */
136    boolean removeEventNotifier(EventNotifier eventNotifier);
137
138    /**
139     * Gets the event factory
140     *
141     * @return event factory
142     */
143    EventFactory getEventFactory();
144
145    /**
146     * Sets the event factory to use
147     *
148     * @param eventFactory event factory
149     */
150    void setEventFactory(EventFactory eventFactory);
151
152    /**
153     * Gets the naming strategy to use
154     *
155     * @return naming strategy
156     */
157    ManagementNamingStrategy getManagementNamingStrategy();
158
159    /**
160     * Sets the naming strategy to use
161     *
162     * @param strategy naming strategy
163     */
164    void setManagementNamingStrategy(ManagementNamingStrategy strategy);
165
166    /**
167     * Gets the object strategy to use
168     *
169     * @return object strategy
170     */
171    ManagementObjectStrategy getManagementObjectStrategy();
172
173    /**
174     * Sets the object strategy to use
175     *
176     * @param strategy object strategy
177     */
178    void setManagementObjectStrategy(ManagementObjectStrategy strategy);
179
180    /**
181     * Gets the management agent
182     *
183     * @return management agent
184     */
185    ManagementAgent getManagementAgent();
186
187    /**
188     * Sets the management agent to use
189     *
190     * @param managementAgent management agent
191     */
192    void setManagementAgent(ManagementAgent managementAgent);
193
194    /**
195     * Filter whether the processor should be managed or not.
196     * <p/>
197     * Is used to filter out unwanted processors to avoid managing at too fine grained level.
198     *
199     * @param definition definition of the processor
200     * @return <tt>true</tt> to manage it
201     */
202    boolean manageProcessor(ProcessorDefinition<?> definition);
203
204    /**
205     * Sets the whether only manage processors if they have been configured with a custom id
206     * <p/>
207     * Default is false.
208     *
209     * @param flag <tt>true</tt> will only manage if custom id was set.
210     */
211    void onlyManageProcessorWithCustomId(boolean flag);
212
213    /**
214     * Checks whether only to manage processors if they have been configured with a custom id
215     *
216     * @return true or false
217     */
218    boolean isOnlyManageProcessorWithCustomId();
219
220    /**
221     * Sets whether load statistics is enabled.
222     *
223     * @param flag <tt>true</tt> to enable load statistics
224     */
225    void setLoadStatisticsEnabled(boolean flag);
226
227    /**
228     * Gets whether load statistics is enabled
229     *
230     * @return <tt>true</tt> if enabled
231     */
232    boolean isLoadStatisticsEnabled();
233
234    /**
235     * Sets the statistics level
236     * <p/>
237     * Default is {@link org.apache.camel.ManagementStatisticsLevel#All}
238     *
239     * @param level the new level
240     */
241    void setStatisticsLevel(ManagementStatisticsLevel level);
242
243    /**
244     * Gets the statistics level
245     *
246     * @return the level
247     */
248    ManagementStatisticsLevel getStatisticsLevel();
249
250}