This page contains the changelog for each release of the kallasoft SmugMug Java API.
Beta 6 [Released 2-09-10]
- Fixed java.lang.ClassCastException: java.lang.Boolean cannot be cast to java.lang.String (JSONUtils.java:53) in the Image entity (used by almost all Image API operations) caused by a change in the SmugMug JSON API from a String value to a Boolean.
Beta 5 [Released 7-19-08]
- Added 2 constructors to every class: 1 default no-arg constructor and a 2-arg (method/argument) constructor. This allows for extensions of the methods to provide replacement method names or argument values without breaking the API. This is most notable in some 1.2.1 and 1.2.2 methods that now accept more arguments than their 1.2.0 counterpart and need to specify those additional arguments.
- Method images.getEXIF was modified to change the types of focalLengthIn35mmFilm and subjectDistanceRange properties from String to Interger to correctly match the EXIF 2.2 spec. Required an update to the SmugMug JSON API as well which got rolled out.
- Added a collection of examples to the download
- Fixed WithPassword userID return type to be Integer instead of int to match the rest of the API.
- Added 1.2.1 albums.applyWatermark method
- Rewrote test library to provide more comprehensive and optimized test coverage
- entity.Image albumID property was changed to return an entity.Album instance. This is more correct as Albums also need their associated Key to perform any operations on them.
- Latitude, Longitude and Altitude properties were added to entity.Image so getting heavy results for images now include the geo-tagging information (e.g. getInfo)
- Support for Latitude, Longitude and Altitude was added to images.ChangeSettings for 1.2.1
- All methods in 1.2.1 that simply wrap 1.2.0 methods were augmented to include more detailed debug logging messages (if logging is enabled) to make method execution tracing more accurate
- 1.2.1 albums.get ShareGroup support added
- 1.2.1 users.getTree ShareGroup support added
- Fixed a bug in 1.2.1 images.Upload method where a warning was logged even if the proper 1.2.1 text-based upload endpoint was used. (NOTE: This only occurred if a debugging logging file was provided)
- Optimized logging by removing wordy & unhelpful trace messages. This also removed a lot of class overhead that previous existed creating class-specific loggers just to log the trace methods. This will lower the memory requirements and optimize runtime a bit.
- Cleaned up Javadoc referring to using APIConstants#UNKNOWN_VALUE when trying to specify an unknown Latitude, Longitude, Altitude and AlbumID/ImageID in the upload methods. This is no longer the case, simply passing null is the correct way.
- APIUtils had 3 new utility methods added to it that implementors are free to use if they need them:
- readStream: used for reading the contents of a stream into a byte
- base64Encode: used to Base64-encode a byte and return the result as a String
- calculateMD5Sum: used to calculate the MD5 Sum of the contents of a byte
- Rewrote implementation of images.Upload to do the following
- Redefine all the common operations that all subclasses will need to use, as utility methods (load, base64 encode, calculate md5 sum)
- Move common pre-processing logic out of the class-specific execute method implementations and into a common implementation-agnostic “prepare” method that all sub-classes can use to prepare text-base uploads if necessary without worrying that they are performing API-version-specific operations.
- This can also be easily extended and enhanced if future upload implementations require slightly different behavior.
- Removed UNKNOWN_VALUE. It is no longer needed since the change the API made from using primitive values to using Object values; now null is a suitable value for unknowns.
- images.Upload, images.UploadFromURL and images.UploadHTTPPut were all reorganized to optimize the calling order of the methods and extract the generic processing functionality into protected methods that any sub-class can make use of without worrying that they are getting version-specific behaviors.
- The version parameter was removed from the UploadHTTPPut method as it made no sense to allow someone to set this to anything other than the version of the API that class was implemented to support.
- NOTE: This could cause a potential compiler error for folks using those convenience methods earlier. The fix is to just remove your version argument; it is set automatically.
Beta 4 [Released 3-24-08]
- REGRESSION: Re-added missing commons-logging library required by HttpClient to run. Sorry guys!
- Support for new SquareThumbnails Album and AlbumTemplate property
Beta 3 [Released 03-08-08]
WARNING: Due to the security changes to the SmugMug API, return type changes and parameter ordering changes, this release will introduce breaks for people building ontop of it. These breaks should be easily worked around for the most part, but if you are having trouble with them, please post to the forums.
Special thanks, again, to David Parry for sending me changes as they were implemented and Anton Spaans for keeping me motivated with excellent feedback.
- Support for Hidden added for images
- Added support for Title argument for album.ChangeSettings method
- Added support for Video (320/640/960/1280) transfer stats to users.GetTransferStats, albums.GetStats, images.GetStats methods
- Support for users.GetTransferStats Heavy and non-Heavy results
- albums.GetInfo and images.GetInfo were changed to return the Album and Image entity type respectively instead of having an internal duplicate of that class. This centralizes changes and future changes in the API to a single class, making it more robust and less likely to break your application built on the API as the SmugMug API changes.
- Support for the new security changes in the SmugMug API was added (see this thread)
- Half of the changes were with respect to Responses now included the key information when appropriate. The other half were to new Key arguments (outlined below)
- The ordering of the arguments for the following methods changed (by adding a Key arg):
- smugmug.albums.getInfo (AlbumKey)
- smugmug.images.get (AlbumKey)
- smugmug.images.getInfo (ImageKey)
- smugmug.images.getURLs (ImageKey)
- smugmug.images.getEXIF (ImageKey)
- The “highlight” property of an Album now represents an Image (ID and Key) and not just the Image ID.
- albums.getStats was changed to return an AlbumTransferStat entity instead of duplicate the class entirely.
- images.getStats was changed to return an ImageTransferStat entity instead of duplicate the class entirely.
- All constants defined for Albums and AlbumTemplates were moved from the 4 associated method classes to the single entity.Album class to help normalize the code.
- Album & AlbumTemplate arguments normalized across the 2 entity classes and 4 method operations, in previous releases some of these arguments were missing.
- Fixed a handful of stray bugs that had to do with argument or parameter mismatches or incorrect Boolean-to-String conversions for Smug.
- 1.2.1 albumtemplates.Create/ChangeSettings/Delete were added.
- All 1.2.0 and 1.2.1 method arguments were changed from using primitives to using Objects. Now all arguments are optional and handled gracefully if omitted. You can simply pass null now for unknown values.
- UploadHTTPPut’s execute implementation was broken up into a execute & executeImpl pair exactly as AbstractMethod provides executeImpl. This allows subclasses to more closely control custom uploading implementations and how to handle the returns JSON response, before the single execute method was written to return a UploadHTTPPutResponse making it very difficult for subclasses to further customize the return at all without hacking up wrapper/delegate Response implementations. This brings the binary upload implementation inline design-wise with the remainder of the API and as flexible as possible while still maintaining the simple ease of use and extensibility.
- Dependency on Commons Logging removed
- Dependency on Commons Lang removed
Beta 2 [Released 12-13-07]
Special thanks to David Parry for his continued hard work on the SmugMug JSON API and Anton Spaans (Author of SmugFig) for bug reports and design suggestions for the kallasoft SmugMug Java API during the Beta 2 development cycle.
- Convenience methods added to every function so you no longer have to work with the cryptic execute(String, String) method calls.
- Support for new Video URL arguments for uploaded videos (Video320URL, Video640URL, Video960URL and Video1280URL)
- Support for SmugMunous added to the 1.2.0 and 1.2.1 APIs
- All response properties changed from primitive types all to objects, which allowed the removal of unchecked exceptions reporting invalid values and simplified the API as well as usage of it.
- users.getTree subcategory support added. Before only categories and their albums were returned, no consideration to subcategories was made.
- Request/Response documentation updated with changed queries for 1.2.0
- User-Agent header changed to report “kallasoft API/0.2.0” where “0.2.0” is replaced with whatever version of the API is being used.
- Added beginning support for SmugMug API 1.2.1
- Optimized response parsing to short-circuit if the response was an error
- Optimized to fail-fast with partial, malformed or corrupted response (values pulled from JSON response are no longer checked for validity first, so errors with API can be detected right away and not hidden. Also removed the need for 1/2 the validity calls against the JSON API)
- smugmug.users.getTree support for SubCategories returned in the response was added.
- Logging was added to the API, using the SLF4J framework. The framework includes logging for all exceptions (as errors), a few strange cases that you should avoid (as warnings) a lot of processing and details (as debug messages) and some tracing messages if you are curious on watching the API’s execution flow.
- This can all be controlled with a LogBack configuration file. A default one that hides all non-error logging is provided by default so the API is “quiet”.
- NOTE: Even though the kallasoft SmugMug Java API already uses Jakarta Commons libraries that require Commons-Logging, Commons-Logging is not a good logging framework and the kallasoft SmugMug Java API may not have the same dependencies across it’s life span. So to decouple the framework from Commons-Logging, SLF4J support was integrated at the outset.
- HttpClient used massively optimized according to the HttpClient Performance Guide.
- Instead of every method call creating an HttpClient instance before calling SmugMug then throwing it away, there is now only one singleton instance of HttpClient used by every request, every time.
- A MultiThreadedHttpConnectionManager is used with the singleton HttpClient to guarantee that multi-threaded use is safe.
- The response from HttpClient is now streamed directly out of the connection instead of being cached in memory, then copied out.
- RuntimeJSONException added. It wraps the checked-exception JSONException from the JSON.org API. Previously all these parse exceptions were caught and stack traces printed out, but it could possibly be valuable for implementors to be able to catch those exceptions and respond to them. RuntimeJSONException will catch the JSONExceptions throw during parsing, and rethrow as an unchecked RuntimeException that can optionally be caught and processed.
- NetworkException is a RuntimeException introduced to encapsulate all potential networking problems that can occur while using the API. Now implementors can simply catch the NetworkException and handle it as they see fit. Additionally getCause can be used to retrieve the more specific exception that occurred (e.g. UnknownHost, NoRouteToHost, ConnectionDenied, etc.)