1 /*
2 * Copyright (c) 1998-2002 The Jgroup Team.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License version 2 as
6 * published by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
16 *
17 */
18
19 package jgroup.core.arm;
20
21 import java.rmi.Remote;
22 import java.rmi.RemoteException;
23 import java.util.Set;
24
25 import jgroup.relacs.config.ClassData;
26
27
28 /**
29 * The <code>ExecService</code> interface describes the methods of an
30 * execution service that can be remotely invoked. Such an execution
31 * service can be used to start other java applications (replicas) on
32 * the remote machine on which the execution service is running.
33 *
34 * @author Hein Meling
35 * @since Jgroup 1.2
36 */
37 public interface ExecService
38 extends Remote
39 {
40
41 /////////////////////////////////////////////////////////////////////////////
42 // Constants
43 /////////////////////////////////////////////////////////////////////////////
44
45 /**
46 * Service name used to register each execution daemon in its local
47 * registry, or bootstrap registry.
48 */
49 public static final String EXEC_DAEMON_NAME = "ExecutionDaemon";
50
51 /**
52 * Keyword used to communicate to a replica that is should do a
53 * graceful shutdown.
54 */
55 public static final String SHUTDOWN_REPLICA = "SHUTDOWN";
56
57
58 /////////////////////////////////////////////////////////////////////////////
59 // Methods
60 /////////////////////////////////////////////////////////////////////////////
61
62 /**
63 * Instantiate and start the given class (replica), within the same
64 * JVM as the execution service. Be aware that starting a new
65 * replica in this way, may cause either the replica(s) or the
66 * execution service to crash due to the failure of only a single
67 * replica. Also, the use of System.exit() from such as replica will
68 * cause the JVM to exit. Thus, this approach should be used with
69 * causion.
70 *
71 * @param classData
72 * The class data object representing the replica to start. The
73 * specified class must implement the remove method.
74 * @return
75 * False if the replica already exists on the associated execution
76 * service; true is returned if the replica was created.
77 *
78 * @throws RemoteException
79 * If remote operation failed.
80 * @throws ExecException
81 * If the specified class (replica) could not be instantiated or
82 * if the class (replica) does not implement the remove method.
83 */
84 public boolean createExecReplica(ClassData classData)
85 throws RemoteException, ExecException;
86
87 /**
88 * Instantiate and start the given class (replica) in a JVM process
89 * separate from the execution service JVM process.
90 *
91 * @param classData
92 * The class data object representing the replica to start.
93 * @return
94 * False if the replica already exists on the associated execution
95 * service; true is returned if the replica was created.
96 *
97 * @throws RemoteException
98 * If remote operation failed.
99 * @throws ExecException
100 * If the specified class (replica) could not be instantiated.
101 */
102 public boolean createReplica(ClassData classData)
103 throws RemoteException, ExecException;
104
105 /**
106 * Remove the specified class (replica) from the execution service
107 * associated with the remote reference.
108 *
109 * @param classData
110 * The class data object representing the replica to start.
111 * @return
112 * False if the specified class (replica) could not be found on
113 * the associated execution service; true if the replica was
114 * successfully removed.
115 *
116 * @throws RemoteException
117 * If remote operation failed.
118 */
119 public boolean removeReplica(ClassData classData)
120 throws RemoteException;
121
122 /**
123 * Return the set of replicas currently running on this execution service.
124 *
125 * @return
126 * The set of class data objects representing replicas that is currently
127 * running within this <code>ExecService</code> instance.
128 * @throws RemoteException
129 * If remote operation failed.
130 */
131 public Set<ClassData> queryReplicas()
132 throws RemoteException;
133
134 /**
135 * Method used to check if the execution service is still running.
136 *
137 * @throws RemoteException
138 * If remote operation failed. This will indicate that the execution
139 * service is no longer running.
140 */
141 public void ping()
142 throws RemoteException;
143
144 /**
145 * Request the execution service on this particular host to shutdown
146 * in approximately <code>delay</code> milliseconds. If delay is negative
147 * all local replicas are removed, and shutdown will be immediate and no
148 * shutdown hooks are executed. If the delay is positive, shutdown hooks
149 * will be executed during the shutdown sequence.
150 *
151 * @param delay
152 * The delay to wait before initiating shutdown.
153 * @throws RemoteException
154 * If remote operation failed. This will indicate that the execution
155 * service is no longer running.
156 */
157 public void shutdown(int delay)
158 throws RemoteException;
159
160 } // END ExecService