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 com.kallasoft.smugmug.api.json.AbstractMethod;
018 import com.kallasoft.smugmug.api.json.AbstractResponse;
019 import com.kallasoft.smugmug.api.json.RuntimeJSONException;
020 import com.kallasoft.smugmug.api.util.APIUtils;
021
022 /**
023 * This method updates specific settings for a given image specified by ImageID.
024 * <p>
025 * If any of the parameters are missing or are empty strings "", they're ignored
026 * and the current settings are preserved, otherwise they're updated with the
027 * new settings.
028 * <p>
029 * This method can be used to update captions, keywords, or to move an image
030 * from one album to another.
031 *
032 * @author Riyad Kalla
033 * @version 1.2.0
034 * @see <a
035 * href="http://smugmug.jot.com/WikiHome/1.2.0/smugmug.images.changeSettings">smugmug.images.changeSettings
036 * API Doc</a>
037 */
038 public class ChangeSettings extends AbstractMethod {
039 /**
040 * Defines the SmugMug JSON API method name that will be called.
041 */
042 public static final String METHOD_NAME = "smugmug.images.changeSettings";
043
044 /**
045 * Defines all the arguments this method takes.
046 * <p>
047 * Values are: "APIKey", "SessionID", "ImageID", "AlbumID", "Caption",
048 * "Keywords", "Hidden"
049 */
050 public static final String[] ARGUMENTS = { "APIKey", "SessionID",
051 "ImageID", "AlbumID", "Caption", "Keywords", "Hidden" };
052
053 /**
054 * Construct a new method instance that can be executed.
055 */
056 public ChangeSettings() {
057 this(METHOD_NAME, ARGUMENTS);
058 }
059
060 /**
061 * Construct a new method instance that can be executed with the given
062 * arguments.
063 *
064 * @param methodName
065 * The name of the SmugMug JSON API method that this
066 * <em>Method</em> represents.
067 * @param arguments
068 * The names of the arguments that this method accepts.
069 */
070 public ChangeSettings(String methodName, String[] arguments) {
071 super(methodName, arguments);
072 }
073
074 /**
075 * Used to execute the smugmug.images.changeSettings method.
076 *
077 * @param url
078 * The URL of the SmugMug server to communicate with.
079 * @param argumentValues
080 * The argument values to pass to this method.
081 *
082 * @return the response that indicates if the operation was successful or
083 * not.
084 */
085 public ChangeSettingsResponse execute(String url, String[] argumentValues) {
086 return new ChangeSettingsResponse(executeImpl(url, argumentValues));
087 }
088
089 /**
090 * Convenience method used to execute the smugmug.images.changeSettings
091 * method.
092 * <p>
093 * This method performs necessary conversions on all the argument values
094 * before calling {@link #execute(String, String[])}.
095 *
096 * @param url
097 * The URL of the SmugMug server to communicate with.
098 * @param apiKey
099 * The API Key to use. API keys are issued by SmugMug.
100 * @param sessionID
101 * The logged in SessionID that represents the user's session.
102 * @param imageID
103 * The ID of the image who will have the change operation
104 * executed on.
105 * @param albumID
106 * The ID of the album that this image will be moved to.
107 *
108 * @return the response that indicates if the operation was successful or
109 * not.
110 *
111 * @see #execute(String, String[])
112 */
113 public ChangeSettingsResponse execute(String url, String apiKey,
114 String sessionID, Integer imageID, Integer albumID) {
115 return execute(url, new String[] { apiKey, sessionID,
116 APIUtils.toString(imageID), APIUtils.toString(albumID) });
117 }
118
119 /**
120 * Convenience method used to execute the smugmug.images.changeSettings
121 * method.
122 * <p>
123 * This method performs necessary conversions on all the argument values
124 * before calling {@link #execute(String, String[])}.
125 *
126 * @param url
127 * The URL of the SmugMug server to communicate with.
128 * @param apiKey
129 * The API Key to use. API keys are issued by SmugMug.
130 * @param sessionID
131 * The logged in SessionID that represents the user's session.
132 * @param imageID
133 * The ID of the image who will have the change operation
134 * executed on.
135 * @param caption
136 * A caption to assign to the given image.
137 * @param keywords
138 * The keywords to assign to the given image.
139 * @param hidden
140 * Set to <code>true</code> to hide the image or
141 * <code>false</code> to leave it unhidden. Default is
142 * <code>false</code>.
143 *
144 * @return the response that indicates if the operation was successful or
145 * not.
146 *
147 * @see #execute(String, String[])
148 */
149 public ChangeSettingsResponse execute(String url, String apiKey,
150 String sessionID, Integer imageID, String caption, String keywords,
151 Boolean hidden) {
152 return execute(url, new String[] { apiKey, sessionID,
153 APIUtils.toString(imageID), null, caption, keywords,
154 APIUtils.toString(hidden) });
155 }
156
157 /**
158 * Class used to represent the response for the
159 * smugmug.images.changeSettings method call.
160 *
161 * @author Riyad Kalla
162 * @version 1.2.0
163 */
164 public class ChangeSettingsResponse extends AbstractResponse {
165 /**
166 * Construct a response by parsing the necessary values out of the JSON
167 * response text.
168 *
169 * @param responseText
170 * The JSON-formatted response text that came back from the
171 * SmugMug API call.
172 *
173 * @throws RuntimeJSONException
174 * if an error occurs while parsing the JSON response text.
175 */
176 public ChangeSettingsResponse(String responseText)
177 throws RuntimeJSONException {
178 /* Parse base response and any error if necessary */
179 super(responseText);
180 }
181
182 @Override
183 public String toString() {
184 return ChangeSettingsResponse.class.getName() + "[isError="
185 + isError() + "]";
186 }
187 }
188 }