com.kallasoft.smugmug.api.json.v1_2_0.images
Class Upload

java.lang.Object
  com.kallasoft.smugmug.api.json.AbstractMethod
      com.kallasoft.smugmug.api.json.v1_2_0.images.Upload

All Implemented Interfaces:

Method

Direct Known Subclasses:

Upload

public class Upload
extends AbstractMethod

This method will upload a file to the specified Album (identified by AlbumID) with the required parameters.

It is recommended that you use the binary upload method UploadHTTPPut instead as it's a more optimized process and doesn't require that the image be Base64 encoded before uploading it, like this method does.

The URL provided to methods in this class should be to the Text-based SmugMug Upload server (APIVersionConstants.TEXT_UPLOAD_SERVER_URL) or the image will not be processed.

The inter-relationships between the methods in this class are as follows:

• execute(String, String[]) passes it's values directly through, as-is, to the super executeImpl method, wrapping the result in an appropriate response.
• execute(String, String, String, Integer, String, InputStream) simply passes it's values, as-is, straight through to execute(String, String, String, Integer, String, InputStream, String, String, Double, Double, Double), including null for values that are unknown.
• execute(String, String, String, Integer, String, InputStream, String, String, Double, Double, Double) utilizes prepareUploadArgumentValues(String, String, Integer, String, InputStream, String, String, Double, Double, Double) to take all the arguments and pre-process them and then assign them, in-order, into a String[] that is immediately passed off to execute(String, String[]) for execution.

Version:

1.2.0

Author:

Riyad Kalla

See Also:

smugmug.images.upload API Doc

Nested Class Summary

class

Upload.UploadResponse Class used to represent the response for the smugmug.images.upload method call.

Field Summary

static String[]	ARGUMENTS Defines all the arguments this method takes.
static String	METHOD_NAME Defines the SmugMug JSON API method name that will be called.

Constructor Summary

Upload()
Construct a new method instance that can be executed.

Upload(String methodName, String[] arguments)
Construct a new method instance that can be executed with the given arguments.

Method Summary

Upload.UploadResponse	execute(String url, String[] argumentValues) Used to execute the smugmug.images.upload method, returning the ID of the uploaded image.
Upload.UploadResponse	execute(String url, String apiKey, String sessionID, Integer albumID, String fileName, InputStream inputStream) Convenience method used to execute the smugmug.images.upload method.
Upload.UploadResponse	execute(String url, String apiKey, String sessionID, Integer albumID, String fileName, InputStream inputStream, String caption, String keywords, Double latitude, Double longitude, Double altitude) Convenience method used to execute the smugmug.images.upload method.
protected String[]	prepareUploadArgumentValues(String apiKey, String sessionID, Integer albumID, String fileName, InputStream inputStream, String caption, String keywords, Double latitude, Double longitude, Double altitude) Convenience method used by this class and can be used by any sub-class to prepare the given arguments by pre-processing the image data and then placing all the resulting values into a String[] that can be then passed directly to execute(String, String[]) to perform the upload.

Methods inherited from class com.kallasoft.smugmug.api.json.AbstractMethod

executeImpl, getArguments, getMethodName, setupPostParameters

Methods inherited from class java.lang.Object

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

Field Detail

METHOD_NAME

public static final String METHOD_NAME

Defines the SmugMug JSON API method name that will be called.

See Also:

Constant Field Values

ARGUMENTS

public static final String[] ARGUMENTS

Defines all the arguments this method takes.

Values are: "APIKey", "SessionID", "AlbumID", "FileName", "Data", "ByteCount", "MD5Sum", "Caption", "Keywords", "Latitude", "Longitude", "Altitude"

Constructor Detail

Upload

public Upload()

Construct a new method instance that can be executed.

Upload

public Upload(String methodName,
              String[] arguments)

Construct a new method instance that can be executed with the given arguments.

Parameters:

methodName - The name of the SmugMug JSON API method that this Method represents.

arguments - The names of the arguments that this method accepts.

Method Detail

execute

public Upload.UploadResponse execute(String url,
                                     String[] argumentValues)

Used to execute the smugmug.images.upload method, returning the ID of the uploaded image.

NOTE: This method calls directly through to AbstractMethod#executeImpl, it does not call into any other method to do pre-processing of it's values.

For methods that offer pre-processing conveniences, please look at the other execute(...) methods defined in this class and check the associated Javadoc with each method to see what it does.

Parameters:

url - The URL of the SmugMug server to communicate with.

argumentValues - The argument values to pass to this method.

Returns:

the response that includes the ID of the uploaded image.

See Also:

execute(String, String, String, Integer, String, InputStream), execute(String, String, String, Integer, String, InputStream, String, String, Double, Double, Double)

execute

public Upload.UploadResponse execute(String url,
                                     String apiKey,
                                     String sessionID,
                                     Integer albumID,
                                     String fileName,
                                     InputStream inputStream)

Convenience method used to execute the smugmug.images.upload method.

This method delegates to execute(String, String, String, Integer, String, InputStream, String, String, Double, Double, Double).

Parameters:

url - The URL of the SmugMug server to communicate with. This usually must be equal to the the SmugMug Upload URL, otherwise the image will not be processed.

apiKey - The API Key to use. API keys are issued by SmugMug.

sessionID - The logged in SessionID that represents the user's session.

albumID - The ID of the album to upload the image into.

fileName - The name of the file whose stream will be read for data and uploaded.

inputStream - The InputStream to load and upload to SmugMug.

Returns:

the response that includes the ID of the uploaded image.

See Also:

execute(String, String[]), execute(String, String, String, Integer, String, InputStream, String, String, Double, Double, Double)

execute

public Upload.UploadResponse execute(String url,
                                     String apiKey,
                                     String sessionID,
                                     Integer albumID,
                                     String fileName,
                                     InputStream inputStream,
                                     String caption,
                                     String keywords,
                                     Double latitude,
                                     Double longitude,
                                     Double altitude)

Convenience method used to execute the smugmug.images.upload method.

This method will perform the following tasks automatically:

1. Load the bytes of the image from the stream, keeping track of the image's size
2. Calculate the MD5 Sum of the image
3. Base64-encode the image data using a highly optimized Base64 encoding algorithm
4. Then delegate the call to execute(String, String[]), passing all the argument values included in the method call along with Data, ByteCount and MD5Sum.

Because of steps 1 and 3, this method will require memory slightly more than twice the size of the image being loaded. Once to load the image data, then again to load the Base64-encoded version of it.

This method performs necessary conversions on all the argument values before calling execute(String, String[]).

NOTE: This method uses prepareUploadArgumentValues(String, String, Integer, String, InputStream, String, String, Double, Double, Double) to do the actual preparation of the image data before delegating to execute(String, String[]).

Parameters:

url - The URL of the SmugMug server to communicate with. This usually must be equal to the the SmugMug Upload URL, otherwise the image will not be processed.

apiKey - The API Key to use. API keys are issued by SmugMug.

sessionID - The logged in SessionID that represents the user's session.

albumID - The ID of the album to upload the image into.

fileName - The name of the file whose stream will be read for data and uploaded.

inputStream - The InputStream to load and upload to SmugMug.

caption - A caption for the image.

keywords - The keywords assigned to the image.

latitude - The latitude used to geocode the image.

longitude - The longitude used to geocode the image.

altitude - The altitude (in meters) used to geocode the image.

Returns:

the response that includes the ID of the uploaded image.

See Also:

execute(String, String[]), prepareUploadArgumentValues(String, String, Integer, String, InputStream, String, String, Double, Double, Double)

prepareUploadArgumentValues

protected String[] prepareUploadArgumentValues(String apiKey,
                                               String sessionID,
                                               Integer albumID,
                                               String fileName,
                                               InputStream inputStream,
                                               String caption,
                                               String keywords,
                                               Double latitude,
                                               Double longitude,
                                               Double altitude)
                                        throws RuntimeException

Convenience method used by this class and can be used by any sub-class to prepare the given arguments by pre-processing the image data and then placing all the resulting values into a String[] that can be then passed directly to execute(String, String[]) to perform the upload.

This method will perform the following operations automatically:

1. Read the image data from the given stream using APIUtils.readStream
2. Base64-encode the read-in image data using APIUtils.base64Encode
3. Calculate the MD5 Sum of the image data that was read in using APIUtils.calculateMD5Sum

Placing all the resulting values, and the rest of the passed in values, in-order, into a String[] and returning it.

Parameters:

apiKey - The API Key to use. API keys are issued by SmugMug.

sessionID - The logged in SessionID that represents the user's session.

albumID - The ID of the album to upload the image into.

fileName - The name of the file whose stream will be read for data and uploaded.

inputStream - The InputStream to load and upload to SmugMug.

caption - A caption for the image.

keywords - The keywords assigned to the image.

latitude - The latitude used to geocode the image.

longitude - The longitude used to geocode the image.

altitude - The altitude (in meters) used to geocode the image.

Returns:

a String[] that represents all the fully prepared argument values that can now be passed directly to the execute(String, String[]) method.

Throws:

RuntimeException - if any of the image operations (readStream, base64Encode or calculateMD5Sum) fail as defined in APIUtils. The thrown exception will wrap the real exception that describes the failure.