com.xerox.amazonws.ec2
Class Jec2

java.lang.Object
  extended by com.xerox.amazonws.common.AWSConnection
      extended by com.xerox.amazonws.common.AWSQueryConnection
          extended by com.xerox.amazonws.ec2.Jec2

public class Jec2
extends AWSQueryConnection

A Java wrapper for the EC2 web services API


Nested Class Summary
static class Jec2.ImageListAttributeOperationType
          Enumerates image list attribute operation types.
 
Field Summary
 
Fields inherited from class com.xerox.amazonws.common.AWSConnection
headers
 
Constructor Summary
Jec2(String awsAccessId, String awsSecretKey)
          Initializes the ec2 service with your AWS login information.
Jec2(String awsAccessId, String awsSecretKey, boolean isSecure)
          Initializes the ec2 service with your AWS login information.
Jec2(String awsAccessId, String awsSecretKey, boolean isSecure, String server)
          Initializes the ec2 service with your AWS login information.
Jec2(String awsAccessId, String awsSecretKey, boolean isSecure, String server, int port)
          Initializes the ec2 service with your AWS login information.
 
Method Summary
 String allocateAddress()
          Allocates an address for this account.
 void associateAddress(String instanceId, String publicIp)
          Associates an address with an instance.
 AttachmentInfo attachVolume(String volumeId, String instanceId, String device)
          Attaches an EBS volume to an instance.
 void authorizeSecurityGroupIngress(String groupName, String ipProtocol, int fromPort, int toPort, String cidrIp)
          Adds incoming permissions to a security group.
 void authorizeSecurityGroupIngress(String groupName, String secGroupName, String secGroupOwnerId)
          Adds incoming permissions to a security group.
 BundleInstanceInfo bundleInstance(String instanceId, String accessId, String bucketName, String prefix, UploadPolicy policy)
          Initiates bundling of an instance running Windows.
 BundleInstanceInfo cancelBundleInstance(String bundleId)
          Cancel a bundling operation.
 List<SpotInstanceCancellationResponse> cancelSpotInstanceRequests(String... sirIds)
           
 ProductInstanceInfo confirmProductInstance(String instanceId, String productCode)
          Returns true if the productCode is associated with the instance.
 String createImage(String instanceId, String name, String description, boolean noReboot)
          Creates an AMI that uses an EBS root device.
 KeyPairInfo createKeyPair(String keyName)
          Creates a public/private keypair.
 void createPlacementGroup(String groupName, String strategy)
          Creates a placement group to launch cluster compute instances into.
 void createSecurityGroup(String name, String desc)
          Creates a security group.
 SnapshotInfo createSnapshot(String volumeId, String description)
          Creates a snapshot of the EBS Volume.
 SpotDatafeedSubscription createSpotDatafeedSubscription(String bucket, String prefix)
          This method creates the spot datafeed subscription (for spot usage logs)
 VolumeInfo createVolume(String size, String snapshotId, String zoneName)
          Creates an EBS volume either by size, or from a snapshot.
 void deleteKeyPair(String keyName)
          Deletes a public/private keypair.
 void deletePlacementGroup(String groupName)
          Deletes a placement group.
 void deleteSecurityGroup(String name)
          Deletes a security group.
 void deleteSnapshot(String snapshotId)
          Deletes the snapshot.
 void deleteSpotDatafeedSubscription()
          This method deletes the spot datafeed subscription
 void deleteVolume(String volumeId)
          Deletes the EBS volume.
 void deregisterImage(String imageId)
          Deregister the given AMI.
 List<AddressInfo> describeAddresses(List<String> addresses)
          Returns a list of addresses associated with this account.
 List<AvailabilityZone> describeAvailabilityZones(List<String> zones)
          Returns a list of availability zones and their status.
 List<BundleInstanceInfo> describeBundleTasks(List<String> bundleIds)
          Returns a list of current bundling tasks.
 List<BundleInstanceInfo> describeBundleTasks(String[] bundleIds)
          Returns a list of current bundling tasks.
 DescribeImageAttributeResult describeImageAttribute(String imageId, ImageAttribute.ImageAttributeType imageAttribute)
          Describes an attribute of an AMI.
 List<ImageDescription> describeImages(List<String> imageIds)
          Describe the given AMIs.
 List<ImageDescription> describeImages(List<String> imageIds, List<String> owners, List<String> users)
          Describe the AMIs that match the intersection of the criteria supplied
protected  List<ImageDescription> describeImages(Map<String,String> params)
           
 List<ImageDescription> describeImages(String[] imageIds)
          Describe the given AMIs.
 List<ImageDescription> describeImagesByExecutability(List<String> users)
          Describe the AMIs executable by supplied users.
 List<ImageDescription> describeImagesByOwner(List<String> owners)
          Describe the AMIs belonging to the supplied owners.
 DescribeInstanceAttributeResult describeInstanceAttribute(String instanceId, String attribute)
          Describes an attribute of an instance.
 List<ReservationDescription> describeInstances(List<String> instanceIds)
          Gets a list of running instances.
 List<ReservationDescription> describeInstances(String[] instanceIds)
          Gets a list of running instances.
 List<KeyPairInfo> describeKeyPairs(List<String> keyIds)
          Lists public/private keypairs.
 List<KeyPairInfo> describeKeyPairs(String[] keyIds)
          Lists public/private keypairs.
 List<PlacementGroupInfo> describePlacementGroups(List<String> groupNames)
          This method describes the placement groups.
 List<RegionInfo> describeRegions(List<String> regions)
          Returns a list of regions
 List<ReservedInstances> describeReservedInstances(List<String> instanceIds)
          Returns a list of Reserved Instance offerings that are available for purchase.
 List<ProductDescription> describeReservedInstancesOfferings(List<String> offeringIds, InstanceType instanceType, String availabilityZone, String productDescription)
          Returns a list of Reserved Instance offerings that are available for purchase.
 List<GroupDescription> describeSecurityGroups(List<String> groupNames)
          Gets a list of security groups and their associated permissions.
 List<GroupDescription> describeSecurityGroups(String[] groupNames)
          Gets a list of security groups and their associated permissions.
 DescribeSnapshotAttributeResult describeSnapshotAttribute(String snapshotId, String attribute)
          Describes an attribute of a snapshot.
 List<SnapshotInfo> describeSnapshots(List<String> snapshotIds)
          Gets a list of EBS snapshots for this account.
 List<SnapshotInfo> describeSnapshots(List<String> snapshotIds, String owner, String restorableBy)
          Gets a list of EBS snapshots for this account.
 List<SnapshotInfo> describeSnapshots(String[] snapshotIds)
          Gets a list of EBS snapshots for this account.
 SpotDatafeedSubscription describeSpotDatafeedSubscription()
          This method describes the spot datafeed subscription
 List<SpotInstanceRequest> describeSpotInstanceRequests()
           
 List<SpotPriceHistoryItem> describeSpotPriceHistory(Calendar start, Calendar end, String productDescription, InstanceType... instanceTypes)
           
 List<VolumeInfo> describeVolumes(List<String> volumeIds)
          Gets a list of EBS volumes for this account.
 List<VolumeInfo> describeVolumes(String[] volumeIds)
          Gets a list of EBS volumes for this account.
 AttachmentInfo detachVolume(String volumeId, String instanceId, String device, boolean force)
          Detaches an EBS volume from an instance.
 void disassociateAddress(String publicIp)
          Disassociates an address with an instance.
 ConsoleOutput getConsoleOutput(String instanceId)
          Get an instance's console output.
 String getPasswordData(String instanceId)
          Get a Windows instance's admin password.
protected
<T> T
makeRequestInt(org.apache.http.client.methods.HttpRequestBase method, String action, Map<String,String> params, Class<T> respType)
           
 void modifyImageAttribute(String imageId, ImageListAttribute attribute, Jec2.ImageListAttributeOperationType operationType)
          Modifies an attribute by the given items with the given operation.
 void modifyInstanceAttribute(String instanceId, String attribute, String value)
          Changes one of a variety of settings for a instance.
 void modifySnapshotAttribute(String snapshotId, String attribute, OperationType opType, String userId, String userGroup)
          Changes permissions settings of a snapshot.
 List<MonitoredInstanceInfo> monitorInstances(List<String> instanceIds)
          This method enables monitoring for some instances
 String purchaseReservedInstancesOffering(String offeringId, int instanceCount)
          This method purchases a reserved instance offering.
 void rebootInstances(List<String> instanceIds)
          Reboot a selection of running instances.
 void rebootInstances(String[] instanceIds)
          Reboot a selection of running instances.
 String registerImage(String imageLocation)
          Register an S3 based AMI.
 String registerImage(String name, String description, String architecture, String kernelId, String ramdiskId, String rootDeviceName, List<BlockDeviceMapping> blockDeviceMappings)
          Register a snapshot as an EBS backed AMI
protected  String registerImage(String imageLocation, String name, String description, String architecture, String kernelId, String ramdiskId, String rootDeviceName, List<BlockDeviceMapping> blockDeviceMappings)
           
 void releaseAddress(String publicIp)
          Releases an address
 List<SpotInstanceRequest> requestSpotInstances(SpotInstanceRequestConfiguration sirc, LaunchConfiguration lc)
           
 void resetImageAttribute(String imageId, ImageAttribute.ImageAttributeType imageAttribute)
          Resets an attribute on an AMI.
 void resetInstanceAttribute(String instanceId, String attribute)
          Resets an attribute on an instance.
 void resetSnapshotAttribute(String snapshotId, String attribute)
          Resets an attribute on a snapshot.
 void revokeSecurityGroupIngress(String groupName, String ipProtocol, int fromPort, int toPort, String cidrIp)
          Revokes incoming permissions from a security group.
 void revokeSecurityGroupIngress(String groupName, String secGroupName, String secGroupOwnerId)
          Revokes incoming permissions from a security group.
 ReservationDescription runInstances(LaunchConfiguration lc)
          Requests reservation of a number of instances.
 ReservationDescription runInstances(String imageId, int minCount, int maxCount, List<String> groupSet, String userData, String keyName)
          Requests reservation of a number of instances.
 ReservationDescription runInstances(String imageId, int minCount, int maxCount, List<String> groupSet, String userData, String keyName, boolean publicAddr)
          Requests reservation of a number of instances.
 ReservationDescription runInstances(String imageId, int minCount, int maxCount, List<String> groupSet, String userData, String keyName, boolean publicAddr, InstanceType type)
          Requests reservation of a number of instances.
 ReservationDescription runInstances(String imageId, int minCount, int maxCount, List<String> groupSet, String userData, String keyName, boolean publicAddr, InstanceType type, String availabilityZone, String kernelId, String ramdiskId, List<BlockDeviceMapping> blockDeviceMappings)
          Requests reservation of a number of instances.
 ReservationDescription runInstances(String imageId, int minCount, int maxCount, List<String> groupSet, String userData, String keyName, InstanceType type)
          Requests reservation of a number of instances.
 void setRegion(RegionInfo region)
          Sets the region to use.
 void setRegionUrl(String regionUrl)
          Sets the region Url to use.
 List<InstanceStateChangeDescription> startInstances(List<String> instanceIds)
          Starts a selection of stopped instances.
 List<InstanceStateChangeDescription> startInstances(String[] instanceIds)
          Starts a selection of stopped instances.
 List<InstanceStateChangeDescription> stopInstances(List<String> instanceIds, boolean force)
          Stops a selection of running instances.
 List<InstanceStateChangeDescription> stopInstances(String[] instanceIds, boolean force)
          Stops a selection of running instances.
 List<InstanceStateChangeDescription> terminateInstances(List<String> instanceIds)
          Terminates a selection of running instances.
 List<InstanceStateChangeDescription> terminateInstances(String[] instanceIds)
          Terminates a selection of running instances.
 List<MonitoredInstanceInfo> unmonitorInstances(List<String> instanceIds)
          This method disables monitoring for some instances
 
Methods inherited from class com.xerox.amazonws.common.AWSQueryConnection
close, close, getConnectionManagerTimeout, getConnectionTimeout, getHeaders, getHttpClient, getMaxConnections, getMaxRetries, getServerTimeZone, getSoTimeout, getString, httpDate, makeRequest, setConnectionManagerTimeout, setConnectionTimeout, setHttpClient, setMaxConnections, setMaxRetries, setProxyValues, setProxyValues, setProxyValues, setServerTimeZone, setSoTimeout, useSystemProxy
 
Methods inherited from class com.xerox.amazonws.common.AWSConnection
encode, encode, getAlgorithm, getAwsAccessKeyId, getPort, getResourcePrefix, getSecretAccessKey, getServer, getSignatureVersion, getUrl, isSecure, makeURL, setResourcePrefix, setServer, setSignatureVersion, urlencode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Jec2

public Jec2(String awsAccessId,
            String awsSecretKey)
Initializes the ec2 service with your AWS login information.

Parameters:
awsAccessId - The your user key into AWS
awsSecretKey - The secret string used to generate signatures for authentication.

Jec2

public Jec2(String awsAccessId,
            String awsSecretKey,
            boolean isSecure)
Initializes the ec2 service with your AWS login information.

Parameters:
awsAccessId - The your user key into AWS
awsSecretKey - The secret string used to generate signatures for authentication.
isSecure - True if the data should be encrypted on the wire on the way to or from EC2.

Jec2

public Jec2(String awsAccessId,
            String awsSecretKey,
            boolean isSecure,
            String server)
Initializes the ec2 service with your AWS login information.

Parameters:
awsAccessId - The your user key into AWS
awsSecretKey - The secret string used to generate signatures for authentication.
isSecure - True if the data should be encrypted on the wire on the way to or from EC2.
server - Which host to connect to. Usually, this will be ec2.amazonaws.com

Jec2

public Jec2(String awsAccessId,
            String awsSecretKey,
            boolean isSecure,
            String server,
            int port)
Initializes the ec2 service with your AWS login information.

Parameters:
awsAccessId - The your user key into AWS
awsSecretKey - The secret string used to generate signatures for authentication.
isSecure - True if the data should be encrypted on the wire on the way to or from EC2.
server - Which host to connect to. Usually, this will be ec2.amazonaws.com
port - Which port to use.
Method Detail

createImage

public String createImage(String instanceId,
                          String name,
                          String description,
                          boolean noReboot)
                   throws EC2Exception
Creates an AMI that uses an EBS root device.

Parameters:
instanceId - An instance's id (ReservationDescription.Instance.instanceId.
name - a name to associate with the image
description - a descriptive string to attach to the image
noReboot - normally false; if set to true, instance is not shutdown first. NOTE: filesystem integrity isn't guaranteed when noReboot=true
Returns:
image ID
Throws:
EC2Exception - wraps checked exceptions

registerImage

public String registerImage(String imageLocation)
                     throws EC2Exception
Register an S3 based AMI.

Parameters:
imageLocation - An AMI path within S3.
Returns:
A unique AMI ID that can be used to create and manage instances of this AMI.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

registerImage

public String registerImage(String name,
                            String description,
                            String architecture,
                            String kernelId,
                            String ramdiskId,
                            String rootDeviceName,
                            List<BlockDeviceMapping> blockDeviceMappings)
                     throws EC2Exception
Register a snapshot as an EBS backed AMI

Parameters:
imageLocation - An AMI path within S3.
Returns:
A unique AMI ID that can be used to create and manage instances of this AMI.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

registerImage

protected String registerImage(String imageLocation,
                               String name,
                               String description,
                               String architecture,
                               String kernelId,
                               String ramdiskId,
                               String rootDeviceName,
                               List<BlockDeviceMapping> blockDeviceMappings)
                        throws EC2Exception
Throws:
EC2Exception

deregisterImage

public void deregisterImage(String imageId)
                     throws EC2Exception
Deregister the given AMI.

Parameters:
imageId - An AMI ID as returned by registerImage(String).
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

describeImages

public List<ImageDescription> describeImages(String[] imageIds)
                                      throws EC2Exception
Describe the given AMIs.

Parameters:
imageIds - An array of AMI IDs as returned by registerImage(String).
Returns:
A list of ImageDescription instances describing each AMI ID.
Throws:
EC2Exception - wraps checked exceptions

describeImages

public List<ImageDescription> describeImages(List<String> imageIds)
                                      throws EC2Exception
Describe the given AMIs.

Parameters:
imageIds - A list of AMI IDs as returned by registerImage(String).
Returns:
A list of ImageDescription instances describing each AMI ID.
Throws:
EC2Exception - wraps checked exceptions

describeImagesByOwner

public List<ImageDescription> describeImagesByOwner(List<String> owners)
                                             throws EC2Exception
Describe the AMIs belonging to the supplied owners.

Parameters:
owners - A list of owners.
Returns:
A list of ImageDescription instances describing each AMI ID.
Throws:
EC2Exception - wraps checked exceptions

describeImagesByExecutability

public List<ImageDescription> describeImagesByExecutability(List<String> users)
                                                     throws EC2Exception
Describe the AMIs executable by supplied users.

Parameters:
users - A list of users.
Returns:
A list of ImageDescription instances describing each AMI ID.
Throws:
EC2Exception - wraps checked exceptions

describeImages

public List<ImageDescription> describeImages(List<String> imageIds,
                                             List<String> owners,
                                             List<String> users)
                                      throws EC2Exception
Describe the AMIs that match the intersection of the criteria supplied

Parameters:
imageIds - A list of AMI IDs as returned by registerImage(String).
owners - A list of owners.
users - A list of users.
Returns:
A list of ImageDescription instances describing each AMI ID.
Throws:
EC2Exception - wraps checked exceptions

describeImages

protected List<ImageDescription> describeImages(Map<String,String> params)
                                         throws EC2Exception
Throws:
EC2Exception

runInstances

public ReservationDescription runInstances(String imageId,
                                           int minCount,
                                           int maxCount,
                                           List<String> groupSet,
                                           String userData,
                                           String keyName)
                                    throws EC2Exception
Requests reservation of a number of instances.

This will begin launching those instances for which a reservation was successfully obtained.

If less than minCount instances are available no instances will be reserved.

NOTE: this method defaults to the AWS desired "public" addressing type. NOTE: this method defaults to the small(traditional) instance type.

Parameters:
imageId - An AMI ID as returned by registerImage(String).
minCount - The minimum number of instances to attempt to reserve.
maxCount - The maximum number of instances to attempt to reserve.
groupSet - A (possibly empty) set of security group definitions.
userData - User supplied data that will be made available to the instance(s)
Returns:
A ReservationDescription describing the instances that have been reserved.
Throws:
EC2Exception - wraps checked exceptions

runInstances

public ReservationDescription runInstances(String imageId,
                                           int minCount,
                                           int maxCount,
                                           List<String> groupSet,
                                           String userData,
                                           String keyName,
                                           boolean publicAddr)
                                    throws EC2Exception
Requests reservation of a number of instances.

This will begin launching those instances for which a reservation was successfully obtained.

If less than minCount instances are available no instances will be reserved. NOTE: this method defaults to the small(traditional) instance type.

Parameters:
imageId - An AMI ID as returned by registerImage(String).
minCount - The minimum number of instances to attempt to reserve.
maxCount - The maximum number of instances to attempt to reserve.
groupSet - A (possibly empty) set of security group definitions.
userData - User supplied data that will be made available to the instance(s)
publicAddr - sets addressing mode to public
Returns:
A ReservationDescription describing the instances that have been reserved.
Throws:
EC2Exception - wraps checked exceptions

runInstances

public ReservationDescription runInstances(String imageId,
                                           int minCount,
                                           int maxCount,
                                           List<String> groupSet,
                                           String userData,
                                           String keyName,
                                           InstanceType type)
                                    throws EC2Exception
Requests reservation of a number of instances.

This will begin launching those instances for which a reservation was successfully obtained.

If less than minCount instances are available no instances will be reserved. NOTE: this method defaults to the AWS desired "public" addressing type.

Parameters:
imageId - An AMI ID as returned by registerImage(String).
minCount - The minimum number of instances to attempt to reserve.
maxCount - The maximum number of instances to attempt to reserve.
groupSet - A (possibly empty) set of security group definitions.
userData - User supplied data that will be made available to the instance(s)
type - instance type
Returns:
A ReservationDescription describing the instances that have been reserved.
Throws:
EC2Exception - wraps checked exceptions

runInstances

public ReservationDescription runInstances(String imageId,
                                           int minCount,
                                           int maxCount,
                                           List<String> groupSet,
                                           String userData,
                                           String keyName,
                                           boolean publicAddr,
                                           InstanceType type)
                                    throws EC2Exception
Requests reservation of a number of instances.

This will begin launching those instances for which a reservation was successfully obtained.

If less than minCount instances are available no instances will be reserved.

Parameters:
imageId - An AMI ID as returned by registerImage(String).
minCount - The minimum number of instances to attempt to reserve.
maxCount - The maximum number of instances to attempt to reserve.
groupSet - A (possibly empty) set of security group definitions.
userData - User supplied data that will be made available to the instance(s)
publicAddr - sets addressing mode to public
type - instance type
Returns:
A ReservationDescription describing the instances that have been reserved.
Throws:
EC2Exception - wraps checked exceptions

runInstances

public ReservationDescription runInstances(String imageId,
                                           int minCount,
                                           int maxCount,
                                           List<String> groupSet,
                                           String userData,
                                           String keyName,
                                           boolean publicAddr,
                                           InstanceType type,
                                           String availabilityZone,
                                           String kernelId,
                                           String ramdiskId,
                                           List<BlockDeviceMapping> blockDeviceMappings)
                                    throws EC2Exception
Requests reservation of a number of instances.

This will begin launching those instances for which a reservation was successfully obtained.

If less than minCount instances are available no instances will be reserved.

Parameters:
imageId - An AMI ID as returned by registerImage(String).
minCount - The minimum number of instances to attempt to reserve.
maxCount - The maximum number of instances to attempt to reserve.
groupSet - A (possibly empty) set of security group definitions.
userData - User supplied data that will be made available to the instance(s)
publicAddr - sets addressing mode to public
type - instance type
availabilityZone - the zone in which to launch the instance(s)
kernelId - id of the kernel with which to launch the instance(s)
ramdiskId - id of the RAM disk with wich to launch the imstance(s)
blockDeviceMappings - mappings of virtual to device names
Returns:
A ReservationDescription describing the instances that have been reserved.
Throws:
EC2Exception - wraps checked exceptions

runInstances

public ReservationDescription runInstances(LaunchConfiguration lc)
                                    throws EC2Exception
Requests reservation of a number of instances.

This will begin launching those instances for which a reservation was successfully obtained.

If less than minCount instances are available no instances will be reserved.

Parameters:
lc - object containing launch configuration
Returns:
A ReservationDescription describing the instances that have been reserved.
Throws:
EC2Exception - wraps checked exceptions

startInstances

public List<InstanceStateChangeDescription> startInstances(String[] instanceIds)
                                                    throws EC2Exception
Starts a selection of stopped instances.

Parameters:
instanceIds - An array of instances (ReservationDescription.Instance.instanceId.
Returns:
A list of InstanceStateChangeDescription instances.
Throws:
EC2Exception - wraps checked exceptions

startInstances

public List<InstanceStateChangeDescription> startInstances(List<String> instanceIds)
                                                    throws EC2Exception
Starts a selection of stopped instances.

Parameters:
instanceIds - A list of instances (ReservationDescription.Instance.instanceId.
Returns:
A list of InstanceStateChangeDescription instances.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

stopInstances

public List<InstanceStateChangeDescription> stopInstances(String[] instanceIds,
                                                          boolean force)
                                                   throws EC2Exception
Stops a selection of running instances.

Parameters:
instanceIds - An array of instances (ReservationDescription.Instance.instanceId.
force - forces the instance to stop. bypasses filesystem flush. Use with caution!
Returns:
A list of InstanceStateChangeDescription instances.
Throws:
EC2Exception - wraps checked exceptions

stopInstances

public List<InstanceStateChangeDescription> stopInstances(List<String> instanceIds,
                                                          boolean force)
                                                   throws EC2Exception
Stops a selection of running instances.

Parameters:
instanceIds - A list of instances (ReservationDescription.Instance.instanceId.
force - forces the instance to stop. bypasses filesystem flush. Use with caution!
Returns:
A list of InstanceStateChangeDescription instances.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

terminateInstances

public List<InstanceStateChangeDescription> terminateInstances(String[] instanceIds)
                                                        throws EC2Exception
Terminates a selection of running instances.

Parameters:
instanceIds - An array of instances (ReservationDescription.Instance.instanceId.
Returns:
A list of InstanceStateChangeDescription instances.
Throws:
EC2Exception - wraps checked exceptions

terminateInstances

public List<InstanceStateChangeDescription> terminateInstances(List<String> instanceIds)
                                                        throws EC2Exception
Terminates a selection of running instances.

Parameters:
instanceIds - A list of instances (ReservationDescription.Instance.instanceId.
Returns:
A list of InstanceStateChangeDescription instances.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

describeInstances

public List<ReservationDescription> describeInstances(String[] instanceIds)
                                               throws EC2Exception
Gets a list of running instances.

If the array of instance IDs is empty then a list of all instances owned by the caller will be returned. Otherwise the list will contain information for the requested instances only.

Parameters:
instanceIds - An array of instances (ReservationDescription.Instance.instanceId.
Returns:
A list of ReservationDescription instances.
Throws:
EC2Exception - wraps checked exceptions

describeInstances

public List<ReservationDescription> describeInstances(List<String> instanceIds)
                                               throws EC2Exception
Gets a list of running instances.

If the list of instance IDs is empty then a list of all instances owned by the caller will be returned. Otherwise the list will contain information for the requested instances only.

Parameters:
instanceIds - A list of instances (ReservationDescription.Instance.instanceId.
Returns:
A list of ReservationDescription instances.
Throws:
EC2Exception - wraps checked exceptions

rebootInstances

public void rebootInstances(String[] instanceIds)
                     throws EC2Exception
Reboot a selection of running instances.

Parameters:
instanceIds - A list of instances (ReservationDescription.Instance.instanceId.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

rebootInstances

public void rebootInstances(List<String> instanceIds)
                     throws EC2Exception
Reboot a selection of running instances.

Parameters:
instanceIds - A list of instances (ReservationDescription.Instance.instanceId.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

modifyInstanceAttribute

public void modifyInstanceAttribute(String instanceId,
                                    String attribute,
                                    String value)
                             throws EC2Exception
Changes one of a variety of settings for a instance.

Parameters:
instanceId - the instance you are addressing
attribute - for now, should be (instanceType|kernel|ramdisk|userData|disableApiTermination|instanceInitatedShutdownBehavior|rootDeviceName|blockDeviceMapping)
value - value of the attribute
Throws:
EC2Exception - wraps checked exceptions

resetInstanceAttribute

public void resetInstanceAttribute(String instanceId,
                                   String attribute)
                            throws EC2Exception
Resets an attribute on an instance.

Parameters:
instanceId - The instance to reset the attribute on.
attribute - The attribute type to reset (kernel|ramdisk).
Throws:
EC2Exception - wraps checked exceptions

describeInstanceAttribute

public DescribeInstanceAttributeResult describeInstanceAttribute(String instanceId,
                                                                 String attribute)
                                                          throws EC2Exception
Describes an attribute of an instance.

Parameters:
instanceId - The instance for which the attribute is described.
attribute - The attribute to describe (createVolumePermission).
Returns:
An object containing the instanceId and a list of list attribute item types and values.
Throws:
EC2Exception - wraps checked exceptions

getConsoleOutput

public ConsoleOutput getConsoleOutput(String instanceId)
                               throws EC2Exception
Get an instance's console output.

Parameters:
instanceId - An instance's id (ReservationDescription.Instance.instanceId.
Returns:
(ConsoleOutput)
Throws:
EC2Exception - wraps checked exceptions

getPasswordData

public String getPasswordData(String instanceId)
                       throws EC2Exception
Get a Windows instance's admin password.

Parameters:
instanceId - An instance's id (ReservationDescription.Instance.instanceId.
Returns:
password data
Throws:
EC2Exception - wraps checked exceptions

createSecurityGroup

public void createSecurityGroup(String name,
                                String desc)
                         throws EC2Exception
Creates a security group.

Parameters:
name - The name of the security group.
desc - The description of the security group.
Throws:
EC2Exception - wraps checked exceptions

deleteSecurityGroup

public void deleteSecurityGroup(String name)
                         throws EC2Exception
Deletes a security group.

Parameters:
name - The name of the security group.
Throws:
EC2Exception - wraps checked exceptions

describeSecurityGroups

public List<GroupDescription> describeSecurityGroups(String[] groupNames)
                                              throws EC2Exception
Gets a list of security groups and their associated permissions.

Parameters:
groupNames - An array of groups to describe.
Returns:
A list of groups (GroupDescription.
Throws:
EC2Exception - wraps checked exceptions

describeSecurityGroups

public List<GroupDescription> describeSecurityGroups(List<String> groupNames)
                                              throws EC2Exception
Gets a list of security groups and their associated permissions.

Parameters:
groupNames - A list of groups to describe.
Returns:
A list of groups (GroupDescription.
Throws:
EC2Exception - wraps checked exceptions

authorizeSecurityGroupIngress

public void authorizeSecurityGroupIngress(String groupName,
                                          String secGroupName,
                                          String secGroupOwnerId)
                                   throws EC2Exception
Adds incoming permissions to a security group.

Parameters:
groupName - name of group to modify
secGroupName - name of security group to authorize access to
secGroupOwnerId - owner of security group to authorize access to
Throws:
EC2Exception - wraps checked exceptions

authorizeSecurityGroupIngress

public void authorizeSecurityGroupIngress(String groupName,
                                          String ipProtocol,
                                          int fromPort,
                                          int toPort,
                                          String cidrIp)
                                   throws EC2Exception
Adds incoming permissions to a security group.

Parameters:
groupName - name of group to modify
ipProtocol - protocol to authorize (tcp, udp, icmp)
fromPort - bottom of port range to authorize
toPort - top of port range to authorize
cidrIp - CIDR IP range to authorize (i.e. 0.0.0.0/0)
Throws:
EC2Exception - wraps checked exceptions

revokeSecurityGroupIngress

public void revokeSecurityGroupIngress(String groupName,
                                       String secGroupName,
                                       String secGroupOwnerId)
                                throws EC2Exception
Revokes incoming permissions from a security group.

Parameters:
groupName - name of group to modify
secGroupName - name of security group to revoke access from
secGroupOwnerId - owner of security group to revoke access from
Throws:
EC2Exception - wraps checked exceptions

revokeSecurityGroupIngress

public void revokeSecurityGroupIngress(String groupName,
                                       String ipProtocol,
                                       int fromPort,
                                       int toPort,
                                       String cidrIp)
                                throws EC2Exception
Revokes incoming permissions from a security group.

Parameters:
groupName - name of group to modify
ipProtocol - protocol to revoke (tcp, udp, icmp)
fromPort - bottom of port range to revoke
toPort - top of port range to revoke
cidrIp - CIDR IP range to revoke (i.e. 0.0.0.0/0)
Throws:
EC2Exception - wraps checked exceptions

createKeyPair

public KeyPairInfo createKeyPair(String keyName)
                          throws EC2Exception
Creates a public/private keypair.

Parameters:
keyName - Name of the keypair.
Returns:
A keypair description (KeyPairInfo).
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

describeKeyPairs

public List<KeyPairInfo> describeKeyPairs(String[] keyIds)
                                   throws EC2Exception
Lists public/private keypairs.

Parameters:
keyIds - An array of keypairs.
Returns:
A list of keypair descriptions (KeyPairInfo).
Throws:
EC2Exception - wraps checked exceptions

describeKeyPairs

public List<KeyPairInfo> describeKeyPairs(List<String> keyIds)
                                   throws EC2Exception
Lists public/private keypairs. NOTE: the KeyPairInfo.getMaterial() method will return null because this API call doesn't return the keypair material.

Parameters:
keyIds - A list of keypairs.
Returns:
A list of keypair descriptions (KeyPairInfo).
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

deleteKeyPair

public void deleteKeyPair(String keyName)
                   throws EC2Exception
Deletes a public/private keypair.

Parameters:
keyName - Name of the keypair.
Throws:
EC2Exception - wraps checked exceptions TODO: need to return request id

modifyImageAttribute

public void modifyImageAttribute(String imageId,
                                 ImageListAttribute attribute,
                                 Jec2.ImageListAttributeOperationType operationType)
                          throws EC2Exception
Modifies an attribute by the given items with the given operation.

Parameters:
imageId - The ID of the AMI to modify the attributes for.
attribute - The name of the attribute to change.
operationType - The name of the operation to change. May be add or remove.
Throws:
EC2Exception - wraps checked exceptions

resetImageAttribute

public void resetImageAttribute(String imageId,
                                ImageAttribute.ImageAttributeType imageAttribute)
                         throws EC2Exception
Resets an attribute on an AMI.

Parameters:
imageId - The AMI to reset the attribute on.
imageAttribute - The attribute type to reset.
Throws:
EC2Exception - wraps checked exceptions

describeImageAttribute

public DescribeImageAttributeResult describeImageAttribute(String imageId,
                                                           ImageAttribute.ImageAttributeType imageAttribute)
                                                    throws EC2Exception
Describes an attribute of an AMI.

Parameters:
imageId - The AMI for which the attribute is described.
imageAttribute - The attribute type to describe.
Returns:
An object containing the imageId and a list of list attribute item types and values.
Throws:
EC2Exception - wraps checked exceptions

confirmProductInstance

public ProductInstanceInfo confirmProductInstance(String instanceId,
                                                  String productCode)
                                           throws EC2Exception
Returns true if the productCode is associated with the instance.

Parameters:
instanceId - An instance's id (ReservationDescription.Instance.instanceId.
productCode - the code for the project you registered with AWS
Returns:
null if no relationship exists, otherwise information about the owner
Throws:
EC2Exception - wraps checked exceptions

describeAvailabilityZones

public List<AvailabilityZone> describeAvailabilityZones(List<String> zones)
                                                 throws EC2Exception
Returns a list of availability zones and their status.

Parameters:
zones - a list of zones to limit the results, or null
Returns:
a list of zones and their availability
Throws:
EC2Exception - wraps checked exceptions

describeAddresses

public List<AddressInfo> describeAddresses(List<String> addresses)
                                    throws EC2Exception
Returns a list of addresses associated with this account.

Parameters:
addresses - a list of zones to limit the results, or null
Returns:
a list of addresses and their associated instance
Throws:
EC2Exception - wraps checked exceptions

allocateAddress

public String allocateAddress()
                       throws EC2Exception
Allocates an address for this account.

Returns:
the new address allocated
Throws:
EC2Exception - wraps checked exceptions

associateAddress

public void associateAddress(String instanceId,
                             String publicIp)
                      throws EC2Exception
Associates an address with an instance.

Parameters:
instanceId - the instance
publicIp - the ip address to associate
Throws:
EC2Exception - wraps checked exceptions

disassociateAddress

public void disassociateAddress(String publicIp)
                         throws EC2Exception
Disassociates an address with an instance.

Parameters:
publicIp - the ip address to disassociate
Throws:
EC2Exception - wraps checked exceptions

releaseAddress

public void releaseAddress(String publicIp)
                    throws EC2Exception
Releases an address

Parameters:
publicIp - the ip address to release
Throws:
EC2Exception - wraps checked exceptions

createVolume

public VolumeInfo createVolume(String size,
                               String snapshotId,
                               String zoneName)
                        throws EC2Exception
Creates an EBS volume either by size, or from a snapshot. The zone must be the same as that of the instance you wish to attach it to.

Parameters:
size - the size of the volume in gigabytes
snapshotId - the snapshot from which to create the new volume
zoneName - the availability zone for the new volume
Returns:
information about the volume
Throws:
EC2Exception - wraps checked exceptions

deleteVolume

public void deleteVolume(String volumeId)
                  throws EC2Exception
Deletes the EBS volume.

Parameters:
volumeId - the id of the volume to be deleted
Throws:
EC2Exception - wraps checked exceptions

describeVolumes

public List<VolumeInfo> describeVolumes(String[] volumeIds)
                                 throws EC2Exception
Gets a list of EBS volumes for this account.

If the array of volume IDs is empty then a list of all volumes owned by the caller will be returned. Otherwise the list will contain information for the requested volumes only.

Parameters:
volumeIds - An array of volumes (VolumeInfo.
Returns:
A list of VolumeInfo volumes.
Throws:
EC2Exception - wraps checked exceptions

describeVolumes

public List<VolumeInfo> describeVolumes(List<String> volumeIds)
                                 throws EC2Exception
Gets a list of EBS volumes for this account.

If the list of volume IDs is empty then a list of all volumes owned by the caller will be returned. Otherwise the list will contain information for the requested volumes only.

Parameters:
volumeIds - A list of volumes (VolumeInfo.
Returns:
A list of VolumeInfo volumes.
Throws:
EC2Exception - wraps checked exceptions

attachVolume

public AttachmentInfo attachVolume(String volumeId,
                                   String instanceId,
                                   String device)
                            throws EC2Exception
Attaches an EBS volume to an instance.

Parameters:
volumeId - the id of the volume
instanceId - the id of the instance
device - the device name for the attached volume
Returns:
the information about this attachment
Throws:
EC2Exception - wraps checked exceptions

detachVolume

public AttachmentInfo detachVolume(String volumeId,
                                   String instanceId,
                                   String device,
                                   boolean force)
                            throws EC2Exception
Detaches an EBS volume from an instance.

Parameters:
volumeId - the id of the volume
instanceId - the id of the instance
device - the device name for the attached volume
force - if true, forces the detachment, only use if normal detachment fails
Returns:
the information about this attachment
Throws:
EC2Exception - wraps checked exceptions

createSnapshot

public SnapshotInfo createSnapshot(String volumeId,
                                   String description)
                            throws EC2Exception
Creates a snapshot of the EBS Volume.

Parameters:
volumeId - the id of the volume
description - an optional descriptive string (256 chars max)
Returns:
information about the snapshot
Throws:
EC2Exception - wraps checked exceptions

deleteSnapshot

public void deleteSnapshot(String snapshotId)
                    throws EC2Exception
Deletes the snapshot.

Parameters:
snapshotId - the id of the snapshot
Throws:
EC2Exception - wraps checked exceptions

describeSnapshots

public List<SnapshotInfo> describeSnapshots(String[] snapshotIds)
                                     throws EC2Exception
Gets a list of EBS snapshots for this account.

If the array of snapshot IDs is empty then a list of all snapshots owned by the caller will be returned. Otherwise the list will contain information for the requested snapshots only.

Parameters:
snapshotIds - An array of snapshots (SnapshotInfo.
Returns:
A list of VolumeInfo volumes.
Throws:
EC2Exception - wraps checked exceptions

describeSnapshots

public List<SnapshotInfo> describeSnapshots(List<String> snapshotIds)
                                     throws EC2Exception
Gets a list of EBS snapshots for this account.

If the list of snapshot IDs is empty then a list of all snapshots owned by the caller will be returned. Otherwise the list will contain information for the requested snapshots only.

Parameters:
snapshotIds - A list of snapshots (SnapshotInfo.
Returns:
A list of VolumeInfo volumes.
Throws:
EC2Exception - wraps checked exceptions

describeSnapshots

public List<SnapshotInfo> describeSnapshots(List<String> snapshotIds,
                                            String owner,
                                            String restorableBy)
                                     throws EC2Exception
Gets a list of EBS snapshots for this account.

If the list of snapshot IDs is empty then a list of all snapshots owned by the caller will be returned. Otherwise the list will contain information for the requested snapshots only.

Parameters:
snapshotIds - A list of snapshots (SnapshotInfo.
owner - limits results to snapshots owned by this user
restorableBy - limits results to account that can create volumes from this snapshot
Returns:
A list of VolumeInfo volumes.
Throws:
EC2Exception - wraps checked exceptions

modifySnapshotAttribute

public void modifySnapshotAttribute(String snapshotId,
                                    String attribute,
                                    OperationType opType,
                                    String userId,
                                    String userGroup)
                             throws EC2Exception
Changes permissions settings of a snapshot.

Parameters:
snapshotId - the snapshot you are addressing
attribute - for now, should be "createVolumePermission"
opType - either add or remove
userId - optional userId (this or userGroup);
userGroup - optional userGroup (this or userId)
Throws:
EC2Exception - wraps checked exceptions

resetSnapshotAttribute

public void resetSnapshotAttribute(String snapshotId,
                                   String attribute)
                            throws EC2Exception
Resets an attribute on a snapshot.

Parameters:
snapshotId - The snapshot to reset the attribute on.
attribute - The attribute to reset (currently just "createVolumePermission").
Throws:
EC2Exception - wraps checked exceptions

describeSnapshotAttribute

public DescribeSnapshotAttributeResult describeSnapshotAttribute(String snapshotId,
                                                                 String attribute)
                                                          throws EC2Exception
Describes an attribute of a snapshot.

Parameters:
snapshotId - The snapshot for which the attribute is described.
attribute - The attribute to describe (createVolumePermission).
Returns:
An object containing the snapshotId and a list of list attribute item types and values.
Throws:
EC2Exception - wraps checked exceptions

describeRegions

public List<RegionInfo> describeRegions(List<String> regions)
                                 throws EC2Exception
Returns a list of regions

Parameters:
regions - a list of regions to limit the results, or null
Returns:
a list of regions and endpoints
Throws:
EC2Exception - wraps checked exceptions

setRegion

public void setRegion(RegionInfo region)
Sets the region to use.

Parameters:
region - the region to use, from describeRegions()

setRegionUrl

public void setRegionUrl(String regionUrl)
Sets the region Url to use.

Parameters:
region - the region Url to use from RegionInfo.getUrl()

bundleInstance

public BundleInstanceInfo bundleInstance(String instanceId,
                                         String accessId,
                                         String bucketName,
                                         String prefix,
                                         UploadPolicy policy)
                                  throws EC2Exception
Initiates bundling of an instance running Windows.

Parameters:
instanceId - the Id of the instance to bundle
accessId - the accessId of the owner of the S3 bucket
bucketName - the name of the S3 bucket in which the AMi will be stored
prefix - the prefix to append to the AMI
policy - an UploadPolicy object containing policy parameters
Returns:
information about the bundle task
Throws:
EC2Exception - wraps checked exceptions

cancelBundleInstance

public BundleInstanceInfo cancelBundleInstance(String bundleId)
                                        throws EC2Exception
Cancel a bundling operation.

Parameters:
bundleId - the Id of the bundle task to cancel
Returns:
information about the cancelled task
Throws:
EC2Exception - wraps checked exceptions

describeBundleTasks

public List<BundleInstanceInfo> describeBundleTasks(String[] bundleIds)
                                             throws EC2Exception
Returns a list of current bundling tasks. An empty array causes all tasks to be returned.

Parameters:
bundleIds - the Ids of the bundle task to describe
Returns:
information about the cancelled task
Throws:
EC2Exception - wraps checked exceptions

describeBundleTasks

public List<BundleInstanceInfo> describeBundleTasks(List<String> bundleIds)
                                             throws EC2Exception
Returns a list of current bundling tasks. An empty list causes all tasks to be returned.

Parameters:
bundleIds - the Ids of the bundle task to describe
Returns:
information about the cancelled task
Throws:
EC2Exception - wraps checked exceptions

describeReservedInstances

public List<ReservedInstances> describeReservedInstances(List<String> instanceIds)
                                                  throws EC2Exception
Returns a list of Reserved Instance offerings that are available for purchase.

Parameters:
instanceIds - specific reserved instance offering ids to return
Throws:
EC2Exception - wraps checked exceptions

describeReservedInstancesOfferings

public List<ProductDescription> describeReservedInstancesOfferings(List<String> offeringIds,
                                                                   InstanceType instanceType,
                                                                   String availabilityZone,
                                                                   String productDescription)
                                                            throws EC2Exception
Returns a list of Reserved Instance offerings that are available for purchase.

Parameters:
offeringIds - specific reserved instance offering ids to return
instanceType - the type of instance offering to be returned
availabilityZone - the availability zone to get offerings for
productDescription - limit results to those with a matching product description
Returns:
a list of product descriptions
Throws:
EC2Exception - wraps checked exceptions

purchaseReservedInstancesOffering

public String purchaseReservedInstancesOffering(String offeringId,
                                                int instanceCount)
                                         throws EC2Exception
This method purchases a reserved instance offering. NOTE: Use With Caution!!! This can cost a lot of money!

Parameters:
offeringId - the id of the offering to purchase
instanceCount - the number of instances to reserve
Returns:
id of reserved instances
Throws:
EC2Exception - wraps checked exceptions

monitorInstances

public List<MonitoredInstanceInfo> monitorInstances(List<String> instanceIds)
                                             throws EC2Exception
This method enables monitoring for some instances

Parameters:
instanceIds - the id of the instances to enable monitoring for
Returns:
information about the monitoring state of those instances
Throws:
EC2Exception - wraps checked exceptions

unmonitorInstances

public List<MonitoredInstanceInfo> unmonitorInstances(List<String> instanceIds)
                                               throws EC2Exception
This method disables monitoring for some instances

Parameters:
instanceIds - the id of the instances to disable monitoring for
Returns:
information about the monitoring state of those instances
Throws:
EC2Exception - wraps checked exceptions

describeSpotPriceHistory

public List<SpotPriceHistoryItem> describeSpotPriceHistory(Calendar start,
                                                           Calendar end,
                                                           String productDescription,
                                                           InstanceType... instanceTypes)
                                                    throws EC2Exception
Throws:
EC2Exception

describeSpotInstanceRequests

public List<SpotInstanceRequest> describeSpotInstanceRequests()
                                                       throws EC2Exception
Throws:
EC2Exception

requestSpotInstances

public List<SpotInstanceRequest> requestSpotInstances(SpotInstanceRequestConfiguration sirc,
                                                      LaunchConfiguration lc)
                                               throws EC2Exception
Throws:
EC2Exception

cancelSpotInstanceRequests

public List<SpotInstanceCancellationResponse> cancelSpotInstanceRequests(String... sirIds)
                                                                  throws EC2Exception
Throws:
EC2Exception

createSpotDatafeedSubscription

public SpotDatafeedSubscription createSpotDatafeedSubscription(String bucket,
                                                               String prefix)
                                                        throws EC2Exception
This method creates the spot datafeed subscription (for spot usage logs)

Parameters:
bucket - the bucket to store the feed in
prefix - the prefix used with the datafeed files
Returns:
information about the subscription
Throws:
EC2Exception - wraps checked exceptions

describeSpotDatafeedSubscription

public SpotDatafeedSubscription describeSpotDatafeedSubscription()
                                                          throws EC2Exception
This method describes the spot datafeed subscription

Returns:
information about the subscription
Throws:
EC2Exception - wraps checked exceptions

deleteSpotDatafeedSubscription

public void deleteSpotDatafeedSubscription()
                                    throws EC2Exception
This method deletes the spot datafeed subscription

Throws:
EC2Exception - wraps checked exceptions

createPlacementGroup

public void createPlacementGroup(String groupName,
                                 String strategy)
                          throws EC2Exception
Creates a placement group to launch cluster compute instances into.

Parameters:
groupName - the name of the group you're creating
strategy - placement strategy ("cluster")
Throws:
EC2Exception - wraps checked exceptions

deletePlacementGroup

public void deletePlacementGroup(String groupName)
                          throws EC2Exception
Deletes a placement group.

Parameters:
groupName - the name of the group you're creating
Throws:
EC2Exception - wraps checked exceptions

describePlacementGroups

public List<PlacementGroupInfo> describePlacementGroups(List<String> groupNames)
                                                 throws EC2Exception
This method describes the placement groups.

Parameters:
groupNames - names of 1 or more groups to get information about, null for all groups
Returns:
information about the groups
Throws:
EC2Exception - wraps checked exceptions

makeRequestInt

protected <T> T makeRequestInt(org.apache.http.client.methods.HttpRequestBase method,
                               String action,
                               Map<String,String> params,
                               Class<T> respType)
                    throws EC2Exception
Throws:
EC2Exception