001/*
002 * JPPF.
003 * Copyright (C) 2005-2015 JPPF Team.
004 * http://www.jppf.org
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.jppf.management.forwarding;
020
021import java.io.Serializable;
022import java.util.Map;
023
024import javax.management.*;
025
026import org.jppf.classloader.DelegationModel;
027import org.jppf.management.NodeSelector;
028import org.jppf.utils.TypedProperties;
029
030/**
031 * MBean interface for forwarding node management requests and monitoring notfications via the driver.
032 * @author Laurent Cohen
033 */
034public interface JPPFNodeForwardingMBean extends Serializable, NotificationEmitter
035{
036  /**
037   * Name of the driver's admin MBean.
038   */
039  String MBEAN_NAME = "org.jppf:name=nodeForwarding,type=driver";
040
041  /**
042   * Invoke a method on the specified MBean of all nodes attached to the driver.
043   * @param selector a filter on the nodes attached tot he driver, determines the nodes to which this method applies.
044   * @param name the name of the MBean.
045   * @param methodName the name of the method to invoke.
046   * @param params the method parameter values.
047   * @param signature the types of the method parameters.
048   * @return a mapping of node uuids to the result of invoking the MBean method on the corresponding node. Each result may be an exception.
049   * <br/>Additionally, each result may be <code>null</code>, in particular if the invoked method has a <code>void</code> return type.
050   * @throws Exception if the invocation failed.
051   */
052  Map<String, Object> forwardInvoke(NodeSelector selector, String name, String methodName, Object[] params, String[] signature) throws Exception;
053
054  /**
055   * Convenience method to invoke an MBean method that has no parameter.
056   * <br/>This is equivalent to calling <code>forwardInvoke(selector, name, methodName, (Object[]) null, (String[]) null)</code>.
057   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
058   * @param name the name of the node MBean to invoke.
059   * @param methodName the name of the method to invoke.
060   * @return a mapping of node uuids to the result of invoking the MBean method on the corresponding node. Each result may be an exception.
061   * <br/>Additionally, each result may be <code>null</code>, in particular if the invoked method has a <code>void</code> return type.
062   * @throws Exception if the invocation failed.
063   */
064  Map<String, Object> forwardInvoke(NodeSelector selector, String name, String methodName) throws Exception;
065
066  /**
067   * Get the value of an attribute of the specified MBean for each specified node.
068   * @param selector a filter on the nodes attached tot he driver, determines the nodes to which this method applies.
069   * @param name the name of the MBean to invoke for each node.
070   * @param attribute the name of the MBean attribute to read.
071   * @return a mapping of node uuids to the result of getting the MBean attribute on the corresponding node. Each result may be an exception.
072   * @throws Exception if the invocation failed.
073   */
074  Map<String, Object> forwardGetAttribute(NodeSelector selector, String name, String attribute) throws Exception;
075
076  /**
077   * Set the value of an attribute of the specified MBean on the specified nodes attached to the driver.
078   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
079   * @param name the name of the MBean to invoke for each node.
080   * @param attribute the name of the MBean attribute to set.
081   * @param value the value to set on the attribute.
082   * @return a mapping of node uuids to an eventual exception resulting from setting the MBean attribute on the corresponding node.
083   * This map may be empty if no exception was raised.
084   * @throws Exception if the invocation failed.
085   */
086  Map<String, Object> forwardSetAttribute(NodeSelector selector, String name, String attribute, Object value) throws Exception;
087
088  /**
089   * Get the latest state information from the node.
090   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
091   * @return a mapping of node uuids to the result of invoking the MBean method on the corresponding node.
092   * Each result may be either a {@link org.jppf.management.JPPFNodeState} object, or an exception if the invocation failed for the corresponding node.
093   * @throws Exception if any error occurs.
094   */
095  Map<String, Object> state(NodeSelector selector) throws Exception;
096
097  /**
098   * Set the size of the specified nodes' thread pool.
099   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
100   * @param size the size as an int.
101   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
102   * This map may be empty if no exception was raised.
103   * @throws Exception if any error occurs.
104   */
105  Map<String, Object> updateThreadPoolSize(NodeSelector selector, Integer size) throws Exception;
106
107  /**
108   * Update the priority of all execution threads for the specified nodes.
109   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
110   * @param newPriority the new priority to set.
111   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
112   * This map may be empty if no exception was raised.
113   * @throws Exception if an error is raised when invoking the node mbean.
114   */
115  Map<String, Object> updateThreadsPriority(NodeSelector selector, Integer newPriority) throws Exception;
116
117  /**
118   * Restart the specified nodes.
119   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
120   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
121   * This map may be empty if no exception was raised.
122   * @throws Exception if any error occurs.
123   */
124  Map<String, Object> restart(NodeSelector selector) throws Exception;
125
126  /**
127   * Restart the specified nodes.
128   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
129   * @param interruptIfRunning whether to restart immediately or wait until each node is idle.
130   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
131   * This map may be empty if no exception was raised.
132   * @throws Exception if any error occurs.
133   */
134  Map<String, Object> restart(NodeSelector selector, Boolean interruptIfRunning) throws Exception;
135
136  /**
137   * Shutdown the specified nodes.
138   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
139   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
140   * This map may be empty if no exception was raised.
141   * @throws Exception if any error occurs.
142   */
143  Map<String, Object> shutdown(NodeSelector selector) throws Exception;
144
145  /**
146   * Shutdown the specified nodes.
147   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
148   * @param interruptIfRunning whether to shutdown immediately or wait until each node is idle.
149   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
150   * This map may be empty if no exception was raised.
151   * @throws Exception if any error occurs.
152   */
153  Map<String, Object> shutdown(NodeSelector selector, Boolean interruptIfRunning) throws Exception;
154
155  /**
156   * Reset the specified nodes' executed tasks counter to zero.
157   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
158   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
159   * This map may be empty if no exception was raised.
160   * @throws Exception if any error occurs.
161   */
162  Map<String, Object> resetTaskCounter(NodeSelector selector) throws Exception;
163
164  /**
165   * Reset the specified nodes' executed tasks counter to the specified value.
166   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
167   * @param n the number to set the task counter to.
168   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
169   * This map may be empty if no exception was raised.
170   * @throws Exception if any error occurs.
171   */
172  Map<String, Object> setTaskCounter(NodeSelector selector, Integer n) throws Exception;
173
174  /**
175   * Update the configuration properties of the specified nodes.
176   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
177   * @param config the set of properties to update.
178   * @param reconnect specifies whether the node should reconnect ot the driver after updating the properties.
179   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
180   * This map may be empty if no exception was raised.
181   * @throws Exception if any error occurs.
182   */
183  Map<String, Object> updateConfiguration(NodeSelector selector, Map<Object, Object> config, Boolean reconnect) throws Exception;
184
185  /**
186   * Cancel the job with the specified id in the specified nodes.
187   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
188   * @param jobId the id of the job to cancel.
189   * @param requeue true if the job should be requeued on the server side, false otherwise.
190   * @return a mapping of node uuids to an eventual exception resulting invoking this method on the corresponding node.
191   * This map may be empty if no exception was raised.
192   * @throws Exception if any error occurs.
193   */
194  Map<String, Object> cancelJob(NodeSelector selector, String jobId, Boolean requeue) throws Exception;
195
196  /**
197   * Get the current class loader delegation model for the specified nodes.
198   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
199   * @return a mapping of node uuids to the result of invoking the MBean method on the corresponding node.
200   * Each result may be either a {@link DelegationModel} enum value, or an exception if the invocation failed for the corresponding node.
201   * @throws Exception if any error occurs.
202   * @see org.jppf.classloader.AbstractJPPFClassLoader#getDelegationModel()
203   */
204  Map<String, Object> getDelegationModel(NodeSelector selector) throws Exception;
205
206  /**
207   * Set the current class loader delegation model for the specified nodes.
208   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
209   * @param model either either {@link org.jppf.classloader.DelegationModel#PARENT_FIRST PARENT_FIRST} or {@link org.jppf.classloader.DelegationModel#URL_FIRST URL_FIRST}.
210   * If any other value is specified then this method has no effect.
211   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
212   * This map may be empty if no exception was raised.
213   * @throws Exception if any error occurs.
214   * @see org.jppf.classloader.AbstractJPPFClassLoader#setDelegationModel(org.jppf.classloader.DelegationModel)
215   */
216  Map<String, Object> setDelegationModel(NodeSelector selector, DelegationModel model) throws Exception;
217
218  /**
219   * Get the system information for the specified nodes.
220   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
221   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
222   * This map may be empty if no exception was raised.
223   * @throws Exception if any error occurs.
224   */
225  Map<String, Object> systemInformation(NodeSelector selector) throws Exception;
226
227  /**
228   * Get the JVM health snapshot for the specified nodes.
229   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
230   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node.
231   * This map may be empty if no exception was raised.
232   * @throws Exception if any error occurs.
233   */
234  Map<String, Object> healthSnapshot(NodeSelector selector) throws Exception;
235
236  /**
237   * Invoke <code>System.gc()</code> on the specified nodes.
238   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
239   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
240   * @throws Exception if any error occurs.
241   */
242  Map<String, Object> gc(NodeSelector selector) throws Exception;
243
244  /**
245   * Get a JVM thread dump for the specified nodes.
246   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
247   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
248   * @throws Exception if any error occurs.
249   */
250  Map<String, Object> threadDump(NodeSelector selector) throws Exception;
251
252  /**
253   * Get the number of provisioned slave nodes for the selected nodes.
254   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
255   * @return a mapping of node uuids to either an {@code int} corresponding tot he number of slaves provisioned by the node,
256   * or an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
257   * @throws Exception if any error occurs.
258   */
259  Map<String, Object> getNbSlaves(NodeSelector selector) throws Exception;
260
261  /**
262   * Start or stop the required number of slaves to reach the specified number on the selected nodes.
263   * This is equivalent to calling {@code provisionSlaveNodes(nbNodes, null)}.
264   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
265   * @param nbNodes the number of slave nodes to reach.
266   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
267   * @throws Exception if any error occurs.
268   */
269  Map<String, Object> provisionSlaveNodes(NodeSelector selector, int nbNodes) throws Exception;
270
271  /**
272   * Start or stop the required number of slaves to reach the specified number on the selected nodes.
273   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
274   * @param nbNodes the number of slave nodes to reach.
275   * @param interruptIfRunning if true then nodes can only be stopped once they are idle. 
276   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
277   * @throws Exception if any error occurs.
278   */
279  Map<String, Object> provisionSlaveNodes(NodeSelector selector, int nbNodes, boolean interruptIfRunning) throws Exception;
280
281  /**
282   * Start or stop the required number of slaves to reach the specified number, using the specified config overrides, on the selected nodes.
283   * <p>If {@code configOverrides} is null, then previous overrides are applied, and already running slave nodes do not need to be stopped.
284   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
285   * @param nbNodes the number of slave nodes to reach.
286   * @param configOverrides the configuration overrides to apply.
287   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
288   * @throws Exception if any error occurs.
289   */
290  Map<String, Object> provisionSlaveNodes(NodeSelector selector, int nbNodes, TypedProperties configOverrides) throws Exception;
291
292  /**
293   * Start or stop the required number of slaves to reach the specified number, using the specified config overrides, on the selected nodes.
294   * <p>If {@code configOverrides} is null, then previous overrides are applied, and already running slave nodes do not need to be stopped.
295   * @param selector a filter on the nodes attached to the driver, determines the nodes to which this method applies.
296   * @param nbNodes the number of slave nodes to reach.
297   * @param interruptIfRunning if true then nodes can only be stopped once they are idle. 
298   * @param configOverrides the configuration overrides to apply.
299   * @return a mapping of node uuids to an eventual exception resulting from invoking this method on the corresponding node. This map may be empty if no exception was raised.
300   * @throws Exception if any error occurs.
301   */
302  Map<String, Object> provisionSlaveNodes(NodeSelector selector, int nbNodes, boolean interruptIfRunning, TypedProperties configOverrides) throws Exception;
303
304  /**
305   * Register a listener with the specified node selector and MBean.
306   * @param selector the node slector to apply to the listener.
307   * @param mBeanName the name of the node mbeans to receive notifications from.
308   * @return a unique id for the listener.
309   * @throws IllegalArgumentException if <code>selector</code> or <code>mBeanName</code> is null.
310   * @exclude
311   */
312  String registerForwardingNotificationListener(NodeSelector selector, final String mBeanName) throws IllegalArgumentException;
313
314  /**
315   * Unregister the specified listener.
316   * @param listenerID the ID of the listener to unregister.
317   * @throws ListenerNotFoundException if the listener could not be found.
318   * @exclude
319   */
320  void unregisterForwardingNotificationListener(String listenerID) throws ListenerNotFoundException;
321}