1 /*
2 * To change this template, choose Tools | Templates
3 * and open the template in the editor.
4 */
5 package cz.cuni.amis.pogamut.base.agent.jmx.adapter;
6
7 import javax.management.MXBean;
8 import javax.management.MalformedObjectNameException;
9 import javax.management.ObjectName;
10
11 import cz.cuni.amis.pogamut.base.agent.exceptions.AgentException;
12 import cz.cuni.amis.pogamut.base.agent.state.level0.IAgentState;
13 import cz.cuni.amis.pogamut.base.component.bus.event.IFatalErrorEvent;
14
15 /**
16 * Interface for the adapter of the Agent MBean.
17 *
18 * @author Ik
19 */
20 @MXBean
21 public interface IAgentMBeanAdapter {
22
23 /**
24 * Returns JMX object name of the MBean.
25 * @param domain jmx domain
26 * @return name under which the MBean should be exported
27 * @throws MalformedObjectNameException
28 */
29 public ObjectName getObjectName(String domain) throws MalformedObjectNameException;
30
31 /**
32 * Returns id of the agent - unique across the JVMs.
33 * @return
34 */
35 public String getComponentId();
36
37 /**
38 * Returns human readable name. getDisplayName is set by agent and doesn't have
39 * to be unique, while getName is machine assigned and is unique.
40 */
41 public String getName();
42
43 /**
44 * Returns the state of the agent (whether it's running / dead / etc.).
45 * <p><p>
46 * Note that the type AgentState wraps two things:
47 * <ul>
48 * <li>AgentStateType that describes the type of the state (init, running, paused, etc.)</li>
49 * <li>String description of the state</li>
50 * </ul>
51 *
52 * @return
53 */
54 public IAgentState getState();
55
56 /**
57 * Attempt to launch the agent. If it does not throw an exception, agent has been successfully started, also
58 * the state of the agent state is changed into Running state.
59 *
60 * @throws AgentException
61 */
62 public void start() throws AgentException;
63
64 /**
65 * This should pause the the agent. If it does not throw an exception, agent has been successfully started,
66 * also the state of the agent state is changed into Paused state.
67 * <BR><BR>
68 * If your agent can't be paused, throw OperationNotSupportedException.
69 *
70 * @throws AgentException
71 */
72 public void pause() throws AgentException;
73
74 /**
75 * This should resume the logic of the agent. If it does not throw an exception, agent has been successfully resumed,
76 * also the state of the agent state is changed into Running state.
77 * <BR><BR>
78 * If your agent can't be paused therefore can't be resumed,
79 * throw OperationNotSupportedException.
80 *
81 * @throws AgentException
82 */
83 public void resume() throws AgentException;
84
85 /**
86 * Attempt to stop the agent, usually meaning dropping all running flags and see whether
87 * it will stop automatically. This method may be blocking. If it does not throw the exception,
88 * the agent has been successfully stopped, also the state of the agent is changed into End state.
89 * <p><p>
90 * If the stop can not complete - it must automatically call kill() method.
91 */
92 public void stop() throws AgentException;
93
94 /**
95 * Stops the agent (unconditionally), closing whatever connection it may have, this
96 * method must be non-blocking + interrupting all the communication, logic or whatever
97 * threads the agent may have.
98 * <p><p>
99 * After calling kill() method, the only method that may be called is getState() to examine state of the agent.
100 * <p><p>
101 * This also equals to "exception happened outside the agent" and "{@link IFatalErrorEvent} should be propagated inside
102 * the agent"
103 */
104 public void kill();
105
106
107 }