View Javadoc

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