001 /* Copyright 2007 kallasoft
002 *
003 * Licensed under the Apache License, Version 2.0 (the "License");
004 * you may not use this file except in compliance with the License.
005 * You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software
010 * distributed under the License is distributed on an "AS IS" BASIS,
011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 * See the License for the specific language governing permissions and
013 * limitations under the License.
014 */
015 package com.kallasoft.smugmug.api.json.v1_2_0.images;
016
017 import org.json.JSONException;
018 import org.json.JSONObject;
019 import org.slf4j.Logger;
020 import org.slf4j.LoggerFactory;
021
022 import com.kallasoft.smugmug.api.json.AbstractMethod;
023 import com.kallasoft.smugmug.api.json.AbstractResponse;
024 import com.kallasoft.smugmug.api.json.RuntimeJSONException;
025 import com.kallasoft.smugmug.api.json.util.JSONUtils;
026 import com.kallasoft.smugmug.api.json.v1_2_0.APIVersionConstants;
027 import com.kallasoft.smugmug.api.util.APIUtils;
028
029 /**
030 * This method will upload a file from a specified URL to the specified Album
031 * (identified by AlbumID) with the required parameters.
032 * <p>
033 * It is recommended that you use the binary upload method {@link UploadHTTPPut}
034 * instead as it's a more optimized process and doesn't require that the image
035 * be Base64 encoded before uploading it, like this method does.
036 * <p>
037 * The URL provided to methods in this class should be to the Text-based SmugMug
038 * Upload server ({@link APIVersionConstants#TEXT_UPLOAD_SERVER_URL}) or the
039 * image will not be processed.
040 *
041 * @author Riyad Kalla
042 * @version 1.2.0
043 * @see <a
044 * href="http://smugmug.jot.com/WikiHome/1.2.0/smugmug.images.uploadFromURL">smugmug.images.uploadFromURL
045 * API Doc</a>
046 */
047 public class UploadFromURL extends AbstractMethod {
048 /**
049 * Defines the SmugMug JSON API method name that will be called.
050 */
051 public static final String METHOD_NAME = "smugmug.images.uploadFromURL";
052
053 /**
054 * Defines all the arguments this method takes.
055 * <p>
056 * Values are: "APIKey", "SessionID", "AlbumID", "URL", "ByteCount",
057 * "MD5Sum", "Caption", "Keywords", "Latitude", "Longitude", "Altitude"
058 */
059 public static final String[] ARGUMENTS = { "APIKey", "SessionID",
060 "AlbumID", "URL", "ByteCount", "MD5Sum", "Caption", "Keywords",
061 "Latitude", "Longitude", "Altitude" };
062
063 private static final Logger logger = LoggerFactory
064 .getLogger(UploadFromURL.class);
065
066 /**
067 * Construct a new method instance that can be executed.
068 */
069 public UploadFromURL() {
070 this(METHOD_NAME, ARGUMENTS);
071 }
072
073 /**
074 * Construct a new method instance that can be executed with the given
075 * arguments.
076 *
077 * @param methodName
078 * The name of the SmugMug JSON API method that this
079 * <em>Method</em> represents.
080 * @param arguments
081 * The names of the arguments that this method accepts.
082 */
083 public UploadFromURL(String methodName, String[] arguments) {
084 super(methodName, arguments);
085 }
086
087 /**
088 * Used to execute the smugmug.images.uploadFromURL method, returning the ID
089 * of the uploaded image.
090 *
091 * @param url
092 * The URL of the SmugMug server to communicate with.
093 * @param argumentValues
094 * The argument values to pass to this method.
095 *
096 * @return the response that includes the ID of the uploaded image.
097 */
098 public UploadFromURLResponse execute(String url, String[] argumentValues) {
099 if (!APIVersionConstants.TEXT_UPLOAD_SERVER_URL.equals(url))
100 logger
101 .warn(
102 "url [{}] should normally be equal to the Text-based SmugMug Upload Server URL (defined by APIVersionConstants.TEXT_UPLOAD_SERVER_URL), otherwise the uploaded image won't be processed.",
103 url);
104
105 return new UploadFromURLResponse(executeImpl(url, argumentValues));
106 }
107
108 /**
109 * Convenience method used to execute the smugmug.images.uploadFromURL
110 * method.
111 * <p>
112 * This method delegates to
113 * {@link #execute(String, String, String, Integer, String, Integer, String, String, String, Double, Double, Double)}.
114 *
115 * @param url
116 * The URL of the SmugMug server to communicate with. This
117 * usually must be equal to the the SmugMug Upload URL, otherwise
118 * the image will not be processed.
119 * @param apiKey
120 * The API Key to use. API keys are issued by SmugMug.
121 * @param sessionID
122 * The logged in SessionID that represents the user's session.
123 * @param albumID
124 * The ID of the album to upload the image into.
125 * @param imageURL
126 * The complete URL to the image to upload (e.g.
127 * http://site.com/funny.jpg).
128 *
129 * @return the response that includes the ID of the uploaded image.
130 *
131 * @see #execute(String, String[])
132 */
133 public UploadFromURLResponse execute(String url, String apiKey,
134 String sessionID, Integer albumID, String imageURL) {
135 return execute(url, apiKey, sessionID, albumID, imageURL, null, null,
136 null, null, null, null, null);
137 }
138
139 /**
140 * Convenience method used to execute the smugmug.images.uploadFromURL
141 * method.
142 * <p>
143 * This method performs necessary conversions on all the argument values
144 * before calling {@link #execute(String, String[])}.
145 *
146 * @param url
147 * The URL of the SmugMug server to communicate with. This
148 * usually must be equal to the the SmugMug Upload URL, otherwise
149 * the image will not be processed.
150 * @param apiKey
151 * The API Key to use. API keys are issued by SmugMug.
152 * @param sessionID
153 * The logged in SessionID that represents the user's session.
154 * @param albumID
155 * The ID of the album to upload the image into.
156 * @param imageURL
157 * The complete URL to the image to upload (e.g.
158 * http://site.com/funny.jpg).
159 * @param byteCount
160 * The byte count for the image being uploaded (if known).
161 * @param md5Sum
162 * The MD5 Sum of the image being uploaded (if known). Use
163 * <code>null</code> if value is unknown.
164 * @param caption
165 * A caption for the image.
166 * @param keywords
167 * The keywords assigned to the image.
168 * @param latitude
169 * The latitude used to geocode the image.
170 * @param longitude
171 * The longitude used to geocode the image.
172 * @param altitude
173 * The altitude (in meters) used to geocode the image.
174 *
175 * @return the response that includes the ID of the uploaded image.
176 *
177 * @see #execute(String, String[])
178 */
179 public UploadFromURLResponse execute(String url, String apiKey,
180 String sessionID, Integer albumID, String imageURL,
181 Integer byteCount, String md5Sum, String caption, String keywords,
182 Double latitude, Double longitude, Double altitude) {
183 return execute(url, new String[] { apiKey, sessionID,
184 APIUtils.toString(albumID), imageURL,
185 APIUtils.toString(byteCount), md5Sum, caption, keywords,
186 APIUtils.toString(latitude), APIUtils.toString(longitude),
187 APIUtils.toString(altitude) });
188 }
189
190 /**
191 * Class used to represent the response for the smugmug.images.uploadFromURL
192 * method call.
193 *
194 * @author Riyad Kalla
195 * @version 1.2.0
196 */
197 public class UploadFromURLResponse extends AbstractResponse {
198 private Integer imageID;
199
200 private String imageKey;
201
202 /**
203 * Construct a response by parsing the necessary values out of the JSON
204 * response text.
205 *
206 * @param responseText
207 * The JSON-formatted response text that came back from the
208 * SmugMug API call.
209 *
210 * @throws RuntimeJSONException
211 * if an error occurs while parsing the JSON response text.
212 */
213 public UploadFromURLResponse(String responseText)
214 throws RuntimeJSONException {
215 /* Parse base response and any error if necessary */
216 super(responseText);
217
218 /* If there was an error, or the message is empty, do nothing */
219 if (isError() || APIUtils.isEmpty(responseText))
220 return;
221
222 JSONObject responseObject = null;
223
224 try {
225 responseObject = new JSONObject(responseText);
226
227 if (!responseObject.isNull("Image")) {
228 JSONObject imageObject = responseObject
229 .getJSONObject("Image");
230
231 imageID = JSONUtils.getIntegerSafely(imageObject, "id");
232 imageKey = JSONUtils.getStringSafely(imageObject, "Key");
233 }
234 } catch (JSONException e) {
235 RuntimeJSONException rje = new RuntimeJSONException(e);
236 logger.error("An error occured parsing the JSON response", rje);
237 throw rje;
238 }
239 }
240
241 @Override
242 public String toString() {
243 return UploadFromURLResponse.class.getName() + "[isError="
244 + isError() + ", imageID=" + getImageID() + ", imageKey="
245 + getImageKey() + "]";
246 }
247
248 /**
249 * Used to get the ID of the uploaded image.
250 *
251 * @return the ID of the uploaded image.
252 */
253 public Integer getImageID() {
254 return imageID;
255 }
256
257 /**
258 * Used to get the security key of the uploaded image.
259 *
260 * @return the security key of the uploaded image.
261 */
262 public String getImageKey() {
263 return imageKey;
264 }
265 }
266 }