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 */
017 package org.apache.camel.spi;
018
019 import java.util.EventObject;
020 import java.util.List;
021
022 import org.apache.camel.ManagementStatisticsLevel;
023 import org.apache.camel.Service;
024 import 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 */
037 public 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 the statistics level
222 * <p/>
223 * Default is {@link org.apache.camel.ManagementStatisticsLevel#All}
224 *
225 * @param level the new level
226 */
227 void setStatisticsLevel(ManagementStatisticsLevel level);
228
229 /**
230 * Gets the statistics level
231 *
232 * @return the level
233 */
234 ManagementStatisticsLevel getStatisticsLevel();
235
236 }