001: /*
002: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
004: *
005: * This program is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU General Public License version
007: * 2 only, as published by the Free Software Foundation.
008: *
009: * This program is distributed in the hope that it will be useful, but
010: * WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * General Public License version 2 for more details (a copy is
013: * included at /legal/license.txt).
014: *
015: * You should have received a copy of the GNU General Public License
016: * version 2 along with this work; if not, write to the Free Software
017: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
018: * 02110-1301 USA
019: *
020: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
021: * Clara, CA 95054 or visit www.sun.com if you need additional
022: * information or have any questions.
023: */
024:
025: package com.sun.jump.isolate.jvmprocess;
026:
027: import com.sun.jump.message.JUMPMessage;
028: import com.sun.jump.message.JUMPMessageHandler;
029:
030: import com.sun.jump.common.JUMPApplication;
031:
032: /**
033: * <code>JUMPAppContainer</code> defines the application container.
034: * The container is responsible for launching the the application class
035: * and hosts the application and handles all the JUMP Isolate related
036: * functionality transparently to the application. It also receives
037: * and processes application model agnostic messages.
038: * <p>
039: * Unless specified for a method, it is assumed that methods catch all
040: * exceptions (but not fatal errors).
041: * <p>
042: * This class is extended by AppModel specific containers.
043: */
044: public abstract class JUMPAppContainer implements JUMPMessageHandler {
045:
046: /**
047: * Creates a new instance of JUMPAppContainer.
048: * An uncheck exception can be thrown from this method to cause
049: * the isolate to exit.
050: */
051: protected JUMPAppContainer() {
052: }
053:
054: /**
055: * Loads, initializes, and signals the <code>JUMPApplication</code> to
056: * enter the <em>Active</em> state.
057: * <p>
058: * In the <em>Active</EM> state the <code>JUMPApplication</code> may
059: * hold resources.
060: * <p>
061: * The method will only be called once per application launch.
062: * <p>
063: * If the <code>JUMPApplication</code> interfaces with the user, it
064: * expected that it will display a user interface before this method
065: * returns.
066: * <p>
067: * If successful, the method must not return until the application is
068: * considered completely initilized and active according to the
069: * application model of the container.
070: *
071: * @param app properties of the application to start
072: * @param args arguments to pass to the application
073: *
074: * @return non-negative container unique runtime ID to identify the
075: * application in future method calls or negative int if the application
076: * can't be started
077: */
078: public abstract int startApp(JUMPApplication app, String[] args);
079:
080: /**
081: * Signals the <code>JUMPApplication</code> to enter
082: * the <em>Paused</em> state.
083: * <p>
084: * In the <em>Paused</em> state the <code>JUMPApplication</code> should
085: * release shared resources and become quiescent. If the application
086: * interfaces with the user it should still be prepared to display its
087: * interface.
088: * <p>
089: * Some application models will not have the concept of <em>Paused</em>
090: * state, in this case the method can be empty.
091: * <p>
092: * This method will only be called called when the
093: * <code>JUMPApplication</code> is in the <em>Active</em> state.
094: * <p>
095: * The method must not return until the application is has responded
096: * to state change according the application model of the container.
097: * <p>
098: * This method should not catch unchecked exceptions, so that caller
099: * can report a failure back to the executive and then the executive may
100: * issue a destroyApp request.
101: *
102: * @param appId runtime ID of the application assigned by startApp
103: */
104: public abstract void pauseApp(int appId);
105:
106: /**
107: * Signals the <code>JUMPApplication</code> that to enter the
108: * <em>Active</em> state.
109: * In the <em>Active</EM> state the <code>JUMPApplication</code> may
110: * hold resources.
111: * <p>
112: * Some application models will not have the concept of <em>Paused</em>
113: * state, in this case the method can be empty.
114: * <p>
115: * The method will only be called when the <code>JUMPApplication</code>
116: * is in the <em>Paused</em> state.
117: * <p>
118: * The method must not return until the application is has responded
119: * to state change according the application model of the container.
120: * <p>
121: * This method should not catch unchecked exceptions, so that caller
122: * can report a failure back to the executive and then the executive may
123: * issue a destroyApp request.
124: *
125: * @param appId runtime ID of the application assigned by startApp
126: */
127: public abstract void resumeApp(int appId);
128:
129: /**
130: * Signals the <code>JUMPApplication</code> to prepare to be terminated
131: * by entering the <em>Destroyed</em> state.
132: * <p>
133: * When entering the <Destroyed</em> state the
134: * <code>JUMPApplication</code> should release all resources gracefully
135: * and saved any persistent state, in preparation for isolate
136: * termination.
137: * <p>
138: * This method may be called from the <em>Paused</em> or <em>Active</em>
139: * states.
140: * <p>
141: * The method must not return until the application is has responded
142: * to state change according the application model of the container.
143: * <p>
144: * If method results in destroying the last application, then this
145: * method should call <code>JUMPAppContainerContext.terminateIsolate</code>
146: * and not <code>System.exit</code>.
147: *
148: * @param appId runtime ID of the application assigned by startApp
149: * @param force If true when this method is called, the
150: * <code>JUMPApplication</code> must cleanup and release all resources.
151: * If false the <code>JUMPApplication</code> may choose to ignore the
152: * request and this method will throw an exception to indicate the
153: * applcation was not destroyed.
154: */
155: public abstract void destroyApp(int appId, boolean force);
156:
157: /**
158: * Handle messages specific to an application model, if needed. This
159: * message would be from a module implemented for the same application
160: * model with a format agreed upon outside JUMP API.
161: *
162: * @param message message from a peer
163: */
164: public void handleMessage(JUMPMessage message) {
165: // call the methods by unpacking the message contents
166: }
167: }
|