com.saucelabs.rest
Class SauceTunnel

java.lang.Object
  com.saucelabs.rest.SauceTunnel

public final class SauceTunnel
extends java.lang.Object

Represents a sauce tunnel server on the cloud.

This object internally holds the status information that it retrieved from the server, and getter methods will work against this state information. To obtain the up-to-date status information from the server, use the refresh() method.

Author:

Kohsuke Kawaguchi

Method Summary

void	connect(int remotePort, java.lang.String localHost, int localPort) Establishes the remote-to-local port forwarding.
void	destroy() Destroys the tunnel server.
void	disconnect(int remotePort) Cancels the remote-to-local port forwarding.
void	disconnectAll() Shuts down all the SSH tunnels opened between the sauce tunnel server and this JVM.
java.util.Date	getCreationTime() Returns the timestamp when this tunnel was created.
java.util.List<java.lang.String>	getDomainNames() Gets the list of the domain names that this tunnel maps to.
java.lang.String	getHost() Gets the tunnel host name inside the Sauce OnDemand cloud.
java.lang.String	getId() Gets the unique ID of this tunnel.
java.util.Date	getShutDownTime() Returns the timestamp when this tunnel was destroyed.
boolean	isRunning() Is this tunnel actively running?
void	refresh() Retrieves the up-to-date status information by contacting the server.
void	waitUntilRunning(long timeout) Waits until the tunnel transitions into the running state, or until the specified timeout expires.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getId

public java.lang.String getId()

Gets the unique ID of this tunnel.

getCreationTime

public java.util.Date getCreationTime()
                               throws java.io.IOException

Returns the timestamp when this tunnel was created.

Throws:

java.io.IOException

getShutDownTime

public java.util.Date getShutDownTime()
                               throws java.io.IOException

Returns the timestamp when this tunnel was destroyed.

Returns:

null If the tunnel is not yet destroyed.

Throws:

java.io.IOException

getHost

public java.lang.String getHost()
                         throws java.io.IOException

Gets the tunnel host name inside the Sauce OnDemand cloud.

Throws:

java.io.IOException

getDomainNames

public java.util.List<java.lang.String> getDomainNames()
                                                throws java.io.IOException

Gets the list of the domain names that this tunnel maps to.

Throws:

java.io.IOException

isRunning

public boolean isRunning()
                  throws java.io.IOException

Is this tunnel actively running?

While it's unclear if all the possible states of the tunnel is a committed part of the API, the tunnel appears to transition from "booting" -> "running" -> "halting". This method returns true iff the status is "running".

Note that the status information isn't updated every time you call this method, so do not call this method in a loop without calling refresh().

Throws:

java.io.IOException

waitUntilRunning

public void waitUntilRunning(long timeout)
                      throws java.io.IOException,
                             java.lang.InterruptedException

Waits until the tunnel transitions into the running state, or until the specified timeout expires.

The method returns normally both in case of time out and successful tunnel start up. Use isRunning() to verify the result.

Parameters:

timeout - number of milli-seconds to wait, or -1 to wait forever. Timeout is approximation and not necessarily accurately honored.

Throws:

java.io.IOException

java.lang.InterruptedException

destroy

public void destroy()
             throws java.io.IOException

Destroys the tunnel server. This will eliminate all the existing SSH tunnels to this server anywhere, not just ones from this JVM. This is not to be confused with disconnectAll().

Throws:

java.io.IOException

connect

public void connect(int remotePort,
                    java.lang.String localHost,
                    int localPort)
             throws java.io.IOException

Establishes the remote-to-local port forwarding.

Throws:

java.io.IOException

disconnect

public void disconnect(int remotePort)
                throws java.io.IOException

Cancels the remote-to-local port forwarding.

Throws:

java.io.IOException

disconnectAll

public void disconnectAll()

Shuts down all the SSH tunnels opened between the sauce tunnel server and this JVM. This is not to be confused with destroy().

refresh

public void refresh()
             throws java.io.IOException

Retrieves the up-to-date status information by contacting the server.

Throws:

java.io.IOException - If the communication fails, or if the tunnel no longer exists.