com.kallasoft.smugmug.api.json
Class AbstractMethod

java.lang.Object
  com.kallasoft.smugmug.api.json.AbstractMethod

All Implemented Interfaces:

Method

Direct Known Subclasses:

Anonymously, ApplyWatermark, ChangePosition, ChangeSettings, ChangeSettings, ChangeSettings, Create, Create, Create, Create, Delete, Delete, Delete, Delete, Delete, Get, Get, Get, Get, Get, GetAll, GetEXIF, GetInfo, GetInfo, GetStats, GetStats, GetTransferStats, GetTree, GetURLs, Logout, Rename, Rename, ReSort, Upload, UploadFromURL, UploadHTTPPut, WithHash, WithPassword

public abstract class AbstractMethod
extends Object
implements Method

Class used to represent the base implementation of a Method in the kallasoft SmugMug Java API.

All custom method implementations should extend this class and provide the additional detail required to support the new method.

The executeImpl(String, String[]) implementation represents the actual implementation of calling the SmugMug JSON API and getting a JSON-formatted reply that it returns to the caller. executeImpl(String, String[]) is the nuts and bolts of the implementation to Method.execute(String, String[]) but it cannot return a specific AbstractResponse instance custom for each Method implementation, so instead it returns the JSON-formatted reply for the caller to parse into an appropriate AbstractResponse instance and return.

The implementation of executeImpl(String, String[]) is fully optimized according to the HttpClient Performance Guide to provide the best performance, memory management, error reporting and resource-cleanup. Because of this, implementors are encouraged to extend this class when implementing their own methods to take advantage of it.

Author:

Riyad Kalla

Constructor Summary

AbstractMethod(String methodName, String[] arguments)
Construct a method that represents the given method name which takes the given arguments.

Method Summary

protected String	executeImpl(String url, String[] argumentValues) The core implementation of the kallasoft SmugMug Java API that takes the given URL and argument values, and communicates with the SmugMug JSON API then returns the JSON-formatted reply to the caller.
String[]	getArguments() Used to get a list of the argument names for this method.
String	getMethodName() Used to get the name of the SmugMug JSON API method that this Method represents and will call when executed.
protected void	setupPostParameters(org.apache.commons.httpclient.methods.PostMethod postMethod, String[] argumentValues) Used to take the given PostMethod and setup all the name/value pairs for it before it is executed.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.kallasoft.smugmug.api.json.Method

execute

Constructor Detail

AbstractMethod

public AbstractMethod(String methodName,
                      String[] arguments)
               throws IllegalArgumentException

Construct a method that represents the given method name which takes 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.

Throws:

IllegalArgumentException - if methodName is null or empty.

Method Detail

getMethodName

public String getMethodName()

Description copied from interface: Method

Used to get the name of the SmugMug JSON API method that this Method represents and will call when executed. For example, smugmug.login.withPassword.

Specified by:

getMethodName in interface Method

Returns:

the name of the SmugMug JSON API method that this method represents and will call when executed.

getArguments

public String[] getArguments()

Description copied from interface: Method

Used to get a list of the argument names for this method. For example, APIKey, SessionID and AlbumID.

Specified by:

getArguments in interface Method

Returns:

a list of the argument names for this method.

setupPostParameters

protected void setupPostParameters(org.apache.commons.httpclient.methods.PostMethod postMethod,
                                   String[] argumentValues)
                            throws IllegalArgumentException

Used to take the given PostMethod and setup all the name/value pairs for it before it is executed.

Any null values for arguments or argumentValues cause that pair of name/value to be ignored. For example, consider the pairs:

• (1, bob)
• (2, mary)
• (3, null)
• (null, scott)

. The first 2 name/value pairs will be included in the HTTP POST, but the 3rd and 4th will be ignored because either their name or value is null.

If more arguments exist than values, all the arguments without matching values will be ignored.

Parameters:

postMethod - The PostMethod that will be setup with all the appropriate name/value pairs in order to call the SmugMug server.

argumentValues - The values to pass to the API call for each of the arguments it takes.

Throws:

IllegalArgumentException - if postMethod is null.

IllegalArgumentException - if methodName is null or empty.

IllegalArgumentException - if either arguments or argumentValues is null.

IllegalArgumentException - if arguments.length < argumentValues.length

executeImpl

protected String executeImpl(String url,
                             String[] argumentValues)
                      throws IllegalArgumentException,
                             NetworkException

The core implementation of the kallasoft SmugMug Java API that takes the given URL and argument values, and communicates with the SmugMug JSON API then returns the JSON-formatted reply to the caller.

Custom Method implementors are encouraged to use this method internally, parsing the JSON reply into the appropriate AbstractResponse then returning that to their caller.

The implementation of this method is fully optimized according to the HttpClient Performance Guide to provide the best performance, memory management, error reporting and resource-cleanup. Because of this, implementors are encouraged to extend this class when implementing their own methods to take advantage of it.

Parameters:

url - The URL of the SmugMug API to call.

argumentValues - The values to pass to the API call for each of the arguments it takes.

Returns:

a JSON-formatted reply from the SmugMug JSON API.

Throws:

IllegalArgumentException - if url is null or empty.

NetworkException - if anything other than a HTTP status code of 200 is returned from the server. This is not the same as a network exception and normally represents a failure on the SmugMug server side.

NetworkException - if any network-based error occurs while trying to communicate with the SmugMug server. This can wrap many different kinds of more specific network-based exceptions. The handler can call getCause() to retrieve a more specific reason for the exception if necessary.