org.dasein.cloud.services.server
Interface ServerServices

public interface ServerServices

Core interface for the server services. Implements all operations critical to managing virtual machines in a cloud environment.

Author:

George Reese @ enStratus (http://www.enstratus.com)

Method Summary

void	boot(String serverId) Boots up a pre-defined server.
Server	clone(String serverId, String intoDcId, String name, String description, boolean powerOn, String... firewallIds) Clones an existing server into a new server.
Server	define(String imageId, ServerSize size, String dataCenterId, String name, boolean withMonitoring, String... firewalls) Defines a server to be booted up at a future point.
String	getConsoleOutput(String serverId, long laterThan) Provides all output from the console of the target server since the specified Unix time.
Collection<String>	getFirewalls(String serverId) Provides a list of firewalls protecting the specified server.
String	getProviderTermForServer(Locale locale) Assists UIs by providing the cloud-specific term for a virtual server in the cloud.
Server	getServer(String serverId) Provides the data from a specific server
ServerPersistence	getServerPersistence() Identifies what kind of server persistence this cloud supports.
ServerStatistics	getServerStatistics(String serverId, long from, long to) Provides hypervisor statistics for the specified server that fit within the defined time range.
Collection<ServerStatistics>	getServerStatisticsForPeriod(String serverId, long from, long to) Provides hypervisor statistics for the specified server that fit within the defined time range.
Collection<ServerSize>	getSupportedSizes(Architecture architecture) Provides a list of instance types, service offerings, or server sizes (however the underlying cloud might describe it) for a particular architecture
boolean	isSupportsCloning()
Server	launch(String imageId, ServerSize size, String dataCenterId, String name, String withKeypairName, String inVlanId, boolean withMonitoring, String... firewalls) Launches a server in the cloud.
Collection<Server>	list() Lists all servers belonging to the account owner currently in the cloud.
void	monitor(String serverId) Turns hypervisor monitoring on for the target server.
void	pause(String serverId) Shuts down the target server.
void	reboot(String serverId) Executes a server reboot for the target server.
void	stop(String serverId) TERMINATES AND DESTROYS the specified server.
void	unmonitor(String serverId) Turns hypervisor monitoring off for the target server.

Method Detail

boot

void boot(String serverId)
          throws InternalException,
                 CloudException

Boots up a pre-defined server. This works only for systems that support persistent servers that can be paused.

Parameters:

serverId - the server to boot up

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

clone

Server clone(String serverId,
             String intoDcId,
             String name,
             String description,
             boolean powerOn,
             String... firewallIds)
             throws InternalException,
                    CloudException

Clones an existing server into a new server.

Parameters:

serverId - the ID of the server to be cloned

intoDcId - the ID of the data center in which the new server will operate

name - the name of the new server

description - a description for the new server

powerOn - power on the new server

firewallIds - a list of firewall IDs to protect the new server

Returns:

a newly deployed server cloned from the original

Throws:

InternalException - an internal error occurred processing the request

CloudException - an error occurred in the cloud processing the request

define

Server define(String imageId,
              ServerSize size,
              String dataCenterId,
              String name,
              boolean withMonitoring,
              String... firewalls)
              throws InternalException,
                     CloudException

Defines a server to be booted up at a future point. This method exists only for clouds that support persistent servers. In other clouds, simply call #launch(String, ServerSize, String, String, boolean, String...). The server will not be started up. To start the server once defined, call boot(String).

Parameters:

imageId - the provider ID for the machine image to use as a base

size - the kind of server to launch

dataCenterId - the provider ID of the data center to which the server will be attached

name - the user-friendly name to be given to the server

withMonitoring - should monitoring be set up for the server

firewalls - a list of firewalls to protect the server

Returns:

the newly created server

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getConsoleOutput

String getConsoleOutput(String serverId,
                        long laterThan)
                        throws InternalException,
                               CloudException

Provides all output from the console of the target server since the specified Unix time.

Parameters:

serverId - the unique ID of the target server

laterThan - the timestamp marking the beginning point of the console output you want

Returns:

the current output from the server console

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getFirewalls

Collection<String> getFirewalls(String serverId)
                                throws InternalException,
                                       CloudException

Provides a list of firewalls protecting the specified server. If firewalls are not supported in this cloud, the list will be empty.

Parameters:

serverId - the server ID whose firewall list is being sought

Returns:

the list of firewalls protecting the target server

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getProviderTermForServer

String getProviderTermForServer(Locale locale)

Assists UIs by providing the cloud-specific term for a virtual server in the cloud.

Parameters:

locale - the locale for which the term should be translated

Returns:

the provider-specific term for a virtual server

getServer

Server getServer(String serverId)
                 throws InternalException,
                        CloudException

Provides the data from a specific server

Parameters:

serverId - the provider ID for the desired server

Returns:

the data behind the target server

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getServerPersistence

ServerPersistence getServerPersistence()
                                       throws InternalException,
                                              CloudException

Identifies what kind of server persistence this cloud supports.

Returns:

the level of server persistence supported buy this cloud

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getServerStatistics

ServerStatistics getServerStatistics(String serverId,
                                     long from,
                                     long to)
                                     throws InternalException,
                                            CloudException

Provides hypervisor statistics for the specified server that fit within the defined time range. For clouds that do not provide hypervisor statistics, this method should return an empty ServerStatistics object and NOT null.

Parameters:

serverId - the unique ID for the target server

from - the beginning of the timeframe for which you want statistics

to - the end of the timeframe for which you want statistics

Returns:

the statistics for the target server

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getServerStatisticsForPeriod

Collection<ServerStatistics> getServerStatisticsForPeriod(String serverId,
                                                          long from,
                                                          long to)
                                                          throws InternalException,
                                                                 CloudException

Provides hypervisor statistics for the specified server that fit within the defined time range. For clouds that do not provide hypervisor statistics, this method should return an empty list.

Parameters:

serverId - the unique ID for the target server

from - the beginning of the timeframe for which you want statistics

to - the end of the timeframe for which you want statistics

Returns:

a collection of discreet server statistics over the specified period

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

getSupportedSizes

Collection<ServerSize> getSupportedSizes(Architecture architecture)
                                         throws InternalException,
                                                CloudException

Provides a list of instance types, service offerings, or server sizes (however the underlying cloud might describe it) for a particular architecture

Parameters:

architecture - the desired architecture size offerings

Returns:

the list of server sizes available for the specified architecture

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

isSupportsCloning

boolean isSupportsCloning()

launch

Server launch(String imageId,
              ServerSize size,
              String dataCenterId,
              String name,
              String withKeypairName,
              String inVlanId,
              boolean withMonitoring,
              String... firewalls)
              throws InternalException,
                     CloudException

Launches a server in the cloud. If the cloud supports persistent servers, this method will first define a server and then boot it. The end result of this operation should be a server that is in the middle of booting up.

Parameters:

imageId - the provider ID of the image from which the server should be built

size - the server size, instance type, or product offering supporting this server

dataCenterId - the provider ID for the data center into which the server will be launched

name - the name of the new server

withKeypairName - the name of the keypair to use for root authentication or null if no keypair

inVlanId - the ID of the VLAN into which the server should be launched, or null if not specifying (or not supported by the cloud)

withMonitoring - whether or not hypervisor monitoring should be enabled for the server

firewalls - the firewalls to protect the new server

Returns:

the newly launched server

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

list

Collection<Server> list()
                        throws InternalException,
                               CloudException

Lists all servers belonging to the account owner currently in the cloud.

Returns:

all servers belonging to the account owner

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

monitor

void monitor(String serverId)
             throws InternalException,
                    CloudException

Turns hypervisor monitoring on for the target server. If the underlying cloud does not support hypervisor monitoring or if the underlying cloud does not allow them to be turned off/on for a running instance, this method will be a NO-OP.

Parameters:

serverId - the provider ID for the server to start monitoring

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

pause

void pause(String serverId)
           throws InternalException,
                  CloudException

Shuts down the target server. This method is a NO-OP in clouds that lack persistent servers. The result of this method should be either a) a server that is still runnning (for non-persistent server clouds) or b) paused and capable of being restarted (for persistent server clouds). In no case should this method cause a destructive event such as the loss of a server.

Parameters:

serverId - the provider ID for the server to pause

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

reboot

void reboot(String serverId)
            throws CloudException,
                   InternalException

Executes a server reboot for the target server.

Parameters:

serverId - the provider ID for the server to reboot

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

stop

void stop(String serverId)
          throws InternalException,
                 CloudException

TERMINATES AND DESTROYS the specified server. If it is running, it will be stopped. Once it is stopped, all of its data will be destroyed and it will no longer be usable. This is a very dangerous operation, especially in clouds with persistent servers.

Parameters:

serverId - the provider ID of the server to be destroyed

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider

unmonitor

void unmonitor(String serverId)
               throws InternalException,
                      CloudException

Turns hypervisor monitoring off for the target server. If the underlying cloud does not support hypervisor monitoring or if the underlying cloud does not allow them to be turned off/on for a running instance, this method will be a NO-OP.

Parameters:

serverId - the provider ID for the server to stop monitoring

Throws:

InternalException - an error occurred within the Dasein Cloud API implementation

CloudException - an error occurred within the cloud provider