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.entity.Image;
026 import com.kallasoft.smugmug.api.util.APIUtils;
027
028 /**
029 * This method will return details about the image specified by ImageID.
030 * <p>
031 * The album must be owned by the Session holder, or else be public (if
032 * password-protected, a password must be provided) to return results, otherwise
033 * an "invalid user" stat code will result. Additionally, some fields are only
034 * returned to the album owner.
035 *
036 * @author Riyad Kalla
037 * @version 1.2.0
038 * @see <a
039 * href="http://smugmug.jot.com/WikiHome/1.2.0/smugmug.images.getInfo">smugmug.images.getInfo
040 * API Doc</a>
041 */
042 public class GetInfo extends AbstractMethod {
043 /**
044 * Defines the SmugMug JSON API method name that will be called.
045 */
046 public static final String METHOD_NAME = "smugmug.images.getInfo";
047
048 /**
049 * Defines all the arguments this method takes.
050 * <p>
051 * Values are: "APIKey", "SessionID", "ImageID", "ImageKey", "Password",
052 * "SitePassword"
053 */
054 public static final String[] ARGUMENTS = { "APIKey", "SessionID",
055 "ImageID", "ImageKey", "Password", "SitePassword" };
056
057 private static final Logger logger = LoggerFactory.getLogger(GetInfo.class);
058
059 /**
060 * Construct a new method instance that can be executed.
061 */
062 public GetInfo() {
063 this(METHOD_NAME, ARGUMENTS);
064 }
065
066 /**
067 * Construct a new method instance that can be executed with the given
068 * arguments.
069 *
070 * @param methodName
071 * The name of the SmugMug JSON API method that this
072 * <em>Method</em> represents.
073 * @param arguments
074 * The names of the arguments that this method accepts.
075 */
076 public GetInfo(String methodName, String[] arguments) {
077 super(methodName, arguments);
078 }
079
080 /**
081 * Used to execute the smugmug.images.getInfo method, returning all the
082 * information about a specific image.
083 *
084 * @param url
085 * The URL of the SmugMug server to communicate with.
086 * @param argumentValues
087 * The argument values to pass to this method.
088 *
089 * @return the response that includes all the information about a specific
090 * image.
091 */
092 public GetInfoResponse execute(String url, String[] argumentValues) {
093 return new GetInfoResponse(executeImpl(url, argumentValues));
094 }
095
096 /**
097 * Convenience method used to execute the smugmug.images.getInfo method.
098 * <p>
099 * This method performs necessary conversions on all the argument values
100 * before calling {@link #execute(String, String[])}.
101 *
102 * @param url
103 * The URL of the SmugMug server to communicate with.
104 * @param apiKey
105 * The API Key to use. API keys are issued by SmugMug.
106 * @param sessionID
107 * The logged in SessionID that represents the user's session.
108 * @param imageID
109 * The ID of the image whose information will be returned.
110 * @param imageKey
111 * The security key for the image.
112 *
113 * @return the response that includes all the information about a specific
114 * image.
115 *
116 * @see #execute(String, String[])
117 */
118 public GetInfoResponse execute(String url, String apiKey, String sessionID,
119 Integer imageID, String imageKey) {
120 return execute(url, new String[] { apiKey, sessionID,
121 APIUtils.toString(imageID), imageKey });
122 }
123
124 /**
125 * Convenience method used to execute the smugmug.images.getInfo method.
126 * <p>
127 * This method performs necessary conversions on all the argument values
128 * before calling {@link #execute(String, String[])}.
129 *
130 * @param url
131 * The URL of the SmugMug server to communicate with.
132 * @param apiKey
133 * The API Key to use. API keys are issued by SmugMug.
134 * @param sessionID
135 * The logged in SessionID that represents the user's session.
136 * @param imageID
137 * The ID of the image whose information will be returned.
138 * @param imageKey
139 * The security key for the image.
140 * @param password
141 * The password to the containing album if necessary.
142 * @param sitePassword
143 * The site password if necessary.
144 *
145 * @return the response that includes all the information about a specific
146 * image.
147 *
148 * @see #execute(String, String[])
149 */
150 public GetInfoResponse execute(String url, String apiKey, String sessionID,
151 Integer imageID, String imageKey, String password,
152 String sitePassword) {
153 return execute(url, new String[] { apiKey, sessionID,
154 APIUtils.toString(imageID), imageKey, password, sitePassword });
155 }
156
157 /**
158 * Class used to represent the response for the smugmug.images.getInfo
159 * method call.
160 *
161 * @author Riyad Kalla
162 * @version 1.2.0
163 */
164 public class GetInfoResponse extends AbstractResponse {
165 private Image image;
166
167 /**
168 * Construct a response by parsing the necessary values out of the JSON
169 * response text.
170 *
171 * @param responseText
172 * The JSON-formatted response text that came back from the
173 * SmugMug API call.
174 *
175 * @throws RuntimeJSONException
176 * if an error occurs while parsing the JSON response text.
177 */
178 public GetInfoResponse(String responseText) throws RuntimeJSONException {
179 /* Parse base response and any error if necessary */
180 super(responseText);
181
182 /* If there was an error, or the message is empty, do nothing */
183 if (isError() || APIUtils.isEmpty(responseText))
184 return;
185
186 JSONObject responseObject = null;
187
188 try {
189 responseObject = new JSONObject(responseText);
190
191 image = new Image(responseObject.getJSONObject("Image"));
192 } catch (JSONException e) {
193 RuntimeJSONException rje = new RuntimeJSONException(e);
194 logger.error("An error occured parsing the JSON response", rje);
195 throw rje;
196 }
197 }
198
199 @Override
200 public String toString() {
201 return GetInfoResponse.class.getName() + "[isError=" + isError()
202 + ", image=" + getImage() + "]";
203 }
204
205 /**
206 * Used to return the image and all it's associated information.
207 *
208 * @return the image and all it's associated information.
209 */
210 public Image getImage() {
211 return image;
212 }
213 }
214 }