001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * If you wish your version of this file to be governed by only the CDDL
025: * or only the GPL Version 2, indicate your decision by adding
026: * "[Contributor] elects to include this software in this distribution
027: * under the [CDDL or GPL Version 2] license." If you do not indicate a
028: * single choice of license, a recipient has the option to distribute
029: * your version of this file under either the CDDL, the GPL Version 2 or
030: * to extend the choice of license to its licensees as provided above.
031: * However, if you add GPL Version 2 code and therefore, elected the GPL
032: * Version 2 license, then the option applies only if the new code is
033: * made subject to such option by the copyright holder.
034: *
035: * Contributor(s):
036: *
037: * Portions Copyrighted 2008 Sun Microsystems, Inc.
038: */
039:
040: package org.netbeans.modules.ruby.railsprojects.server.spi;
041:
042: import java.io.File;
043: import java.util.concurrent.Future;
044: import javax.swing.event.ChangeListener;
045: import org.netbeans.api.ruby.platform.RubyPlatform;
046:
047: /**
048: * Ruby Server API
049: *
050: * An implementation of this interface provides the ability to start, stop,
051: * and administer a server instance offering Ruby runtime capabilities to the
052: * NetBeans IDE.
053: *
054: * @author Peter Williams
055: */
056: public interface RubyInstance {
057:
058: /**
059: * Enum for the current state of the server (stopped, running, etc.)
060: */
061: public static enum ServerState {
062: STOPPED, // Server is not running or otherwise unavailable.
063: STARTING, // Server is in the process of starting up.
064: RUNNING, // Server is running and available.
065: STOPPING
066: // Server is in the process of stopping.
067: };
068:
069: /**
070: * Enum for the current state of a server operation (e.g start, stop, deploy)
071: */
072: public static enum OperationState {
073: RUNNING, // Operation is running.
074: COMPLETED, // Operation completed successfully.
075: FAILED
076: // Operation failed.
077: }
078:
079: /**
080: * Immutable object combining an operation state with a useful message about
081: * how the operation ended up in that state, e.g. failure message, running
082: * server greeting, etc.
083: */
084: public static class OperationResult {
085:
086: public final OperationState operationState;
087: public final ServerState serverState;
088: public final String message;
089:
090: /**
091: * Constructor for an OperationResult object describing the current
092: * status of an operation.
093: *
094: * @param operationState Status of operation for this result.
095: * @param serverState Server state at the time of this result.
096: * @param message Message describing result, e.g. failure message, etc.
097: */
098: public OperationResult(final OperationState operationState,
099: final ServerState serverState, final String message) {
100: this .operationState = operationState;
101: this .serverState = serverState;
102: this .message = message;
103: }
104: }
105:
106: /**
107: * Get the URI that uniquely identifies this Ruby Server Instance
108: *
109: * @return URI for this ruby server instance.
110: */
111: public String getServerUri();
112:
113: /**
114: * Get a user displayable name for this server instance.
115: *
116: * @return The name of this server instance, in user displayable form.
117: */
118: public String getDisplayName();
119:
120: /**
121: * Returns current state of server (starting, running, stopping, stopped, etc.)
122: *
123: * The implementation of this method must be threadsafe.
124: *
125: * TODO Should ServerState be defined in common server SPI? Is it really API?
126: *
127: * @return Current state of server (starting, running, stopped, etc.)
128: */
129: public ServerState getServerState();
130:
131: /**
132: * Start the server using the given <code>platform</code>, or if a
133: * <code>null</code> was passed, using the "default" platform of the server.
134: *
135: * @param platform the platform to use or <code>null</code>.
136: *
137: * @return true if startup succeeded and server is running, false otherwise.
138: */
139: public Future<OperationState> startServer(RubyPlatform platform);
140:
141: /**
142: * Stop the server
143: *
144: * @return true if server successfully stopped (or was already stopped), false
145: * if server is still running or otherwise unresponsive.
146: */
147: public Future<OperationState> stopServer();
148:
149: /**
150: * Deploy the ruby application in the specified folder to the server.
151: *
152: * TODO Should rails be assumed here? How will we handle alternative web
153: * frameworks? They should not require additional api methods (though they
154: * may require additional parameters).
155: *
156: * TODO Need better error reporting for this result, asynchronous or not.
157: * Perhaps use Future<OperationResult> which combines the operation state
158: * with a message.
159: *
160: * @param applicationName name to assign to deployed application (defaults
161: * to directory or jar name if null or empty).
162: * @param applicationDir directory containing Ruby (Rails?) application.
163: *
164: * @return true if the application was successfully deployed, false otherwise.
165: */
166: public Future<OperationState> deploy(String applicationName,
167: File applicationDir);
168:
169: /**
170: * Stops the application at the specified location, if it is currently running
171: * (e.g. servicing requests).
172: *
173: * @param applicationName name assigned to previously deployed application.
174: * Use directory or jar name if no application name was originally specified.
175: *
176: * @return true if the application was stopped (or was not running), false otherwise.
177: */
178: public Future<OperationState> stop(String applicationName);
179:
180: /**
181: * Executes the application against this server. Starts or restarts server
182: * if necessary, deploys application to server and enables it.
183: *
184: * @param platform the platform to use or <code>null</code>.
185: * @param applicationName name to assign to deployed application (defaults
186: * to directory or jar name if null or empty).
187: * @param applicationDir directory containing Ruby (Rails?) application.
188: *
189: * @return true if server was successfully started (if necessary) and if
190: * application was successfully deployed and executed.
191: */
192: public Future<OperationState> runApplication(RubyPlatform platform,
193: String applicationName, File applicationDir);
194:
195: /**
196: * Checks whether the given <code>platform</code> is supported by
197: * this instance. In other words, checks whether this instance can
198: * be used for running applications with the given <code>platform</code>.
199: *
200: * @param platform the platform to check; must not be null.
201: * @return true if the given <code>platform</code> is supported by this
202: * instances, false otherwise.
203: */
204: public boolean isPlatformSupported(RubyPlatform platform);
205:
206: /**
207: * Add a change listener to receive changes in server state from this server
208: * instance. Listener implementation can call getServerState() to determine
209: * the current state.
210: *
211: * @param listener Listener to receive change events whenever the running
212: * state of this server instance changes.
213: */
214: public void addChangeListener(ChangeListener listener);
215:
216: /**
217: * Remove a change listener previously added to this server instance.
218: *
219: * @param listener Listener that was being notified of state change events
220: * from this server instance.
221: */
222: public void removeChangeListener(ChangeListener listener);
223:
224: /**
225: * Returns the context path for the specified application on this server.
226: *
227: * @return the context path for the specified application.
228: */
229: public String getContextRoot(String applicationName);
230:
231: /**
232: * The http port used for accessing rails apps for this server.
233: *
234: * @return http port for rails on this server.
235: */
236: public int getRailsPort();
237:
238: }
|